Production-Grade Whapi n8n Node

A comprehensive n8n community node for WhapiCloud that enables powerful WhatsApp automation with extensive features and robust error handling.

Overview

This production-grade n8n node provides seamless integration with WhapiCloud's WhatsApp API, offering a significant enhancement over basic implementations. Built with TypeScript and following n8n's best practices, it supports comprehensive WhatsApp automation including messaging, media handling, group management, and advanced features like stories, newsletters, and presence management.

Features

Core Capabilities

• Comprehensive Message Support: Send and receive text, media (images, videos, audio, documents), locations, contacts, polls, and interactive messages
• Advanced Message Management: Mark as read, delete, react with emojis, star, pin, and forward messages
• Group Operations: Create, manage, and interact with WhatsApp groups including participant management and settings
• Contact Management: Verify phone numbers, manage contacts, and handle contact sharing
• Presence Control: Manage online status, typing indicators, and presence subscriptions
• Stories/Status Management: Create, publish, and manage WhatsApp stories
• Newsletter/Channel Support: Full support for WhatsApp channels including creation and management
• User Authentication: QR code and phone number-based authentication
• Channel Health Monitoring: Check API health, limits, and configuration

Technical Excellence

• Type-Safe Implementation: Full TypeScript support with comprehensive type definitions
• Robust Error Handling: Detailed error mapping with user-friendly messages and retry mechanisms
• Modular Architecture: Clean, maintainable code structure with separation of concerns
• Production-Ready: Built following enterprise-grade development practices
• Extensive Validation: Input validation and data sanitization throughout

Installation

From npm (Recommended)

npm install n8n-nodes-whapi-production --legacy-peer-deps

Note: The --legacy-peer-deps flag is required to bypass dependency conflicts with ESLint packages. This does not affect the functionality of the node.

From Source

1. Clone the repository:

git clone https://github.com/Whapi-Cloud/n8n-nodes-whapi-production.git
cd n8n-nodes-whapi-production

2. Install dependencies:

npm install

3. Build the node:

npm run build

4. Link for local development:

npm link

Configuration

Credentials Setup

1. Obtain Whapi API Token:

   • Sign up at Whapi.Cloud
   • Create a new channel
   • Copy your API token from the dashboard

2. Configure n8n Credentials:

   • In n8n, go to Settings → Credentials
   • Create new credentials of type "Whapi Channel API"
   • Enter your API token and base URL (default: https://gate.whapi.cloud)

Basic Usage

1. Add the Whapi node to your workflow
2. Select your configured credentials
3. Choose a resource (Messages, Groups, Contacts, etc.)
4. Select an operation
5. Configure the required parameters

Supported Resources and Operations

Messages Resource

The Messages resource provides comprehensive messaging capabilities for WhatsApp automation.

Send Text Message

Send plain text messages with advanced options including mentions, link previews, and message quoting.

Parameters:

• chatId (required): Target chat ID or phone number
• text (required): Message content
• quoted (optional): ID of message to reply to
• linkPreview (optional): Enable/disable link previews
• mentions (optional): Comma-separated phone numbers to mention

Example Usage:

// Send a simple text message
{
  "chatId": "[email protected]",
  "text": "Hello from n8n automation!"
}

// Send with mentions and reply
{
  "chatId": "[email protected]",
  "text": "Hello @1234567890, thanks for your message!",
  "mentions": "1234567890",
  "quoted": "message_id_to_reply_to"
}

Send Media Message

Send various media types including images, videos, audio, documents, and stickers.

Parameters:

• chatId (required): Target chat ID or phone number
• mediaType (required): Type of media (image, video, audio, voice, document, sticker)
• mediaUrl (required): URL of the media file
• caption (optional): Media caption (for images, videos, documents)
• filename (optional): Custom filename (for documents, audio, voice)
• viewOnce (optional): Make media disappear after viewing (images, videos only)

Example Usage:

// Send an image with caption
{
  "chatId": "[email protected]",
  "mediaType": "image",
  "mediaUrl": "https://example.com/image.jpg",
  "caption": "Check out this amazing photo!"
}

// Send a document
{
  "chatId": "[email protected]",
  "mediaType": "document",
  "mediaUrl": "https://example.com/report.pdf",
  "filename": "Monthly_Report.pdf"
}

Get Messages

Retrieve messages from chats with filtering and pagination options.

Parameters:

• chatId (optional): Specific chat to retrieve messages from
• limit (optional): Maximum number of messages (default: 50)
• offset (optional): Number of messages to skip
• fromMe (optional): Filter messages sent by current user
• includeMedia (optional): Include media messages
• messageType (optional): Filter by message type

Message Management Operations

• Mark as Read: Mark specific messages as read
• Delete Message: Delete messages from chats
• React to Message: Add or remove emoji reactions
• Star Message: Star important messages
• Pin Message: Pin messages in chats
• Forward Message: Forward existing messages to other chats

Groups Resource

Comprehensive group management capabilities for WhatsApp groups.

Create Group

Create new WhatsApp groups with initial participants and settings.

Parameters:

• name (required): Group name
• description (optional): Group description
• participants (required): Array of phone numbers to add
• picture (optional): Group picture URL

Group Management Operations

• Get Groups: Retrieve list of all groups
• Update Group Info: Modify group name, description, or picture
• Leave Group: Exit from groups
• Add/Remove Participants: Manage group membership
• Promote/Demote Admins: Manage group administration
• Group Settings: Configure who can send messages, edit info, etc.
• Invite Management: Create, revoke, and manage group invite links
• Join Requests: Handle pending join requests for groups

Contacts Resource

Manage contacts and verify WhatsApp numbers.

Check Phones

Verify if phone numbers are registered on WhatsApp.

Parameters:

• phones (required): Array of phone numbers to check

Contact Operations

• Get Contacts: Retrieve contact list
• Get Contact Details: Get information about specific contacts
• Send Contact: Share contacts with other chats
• Get Profile: Retrieve contact profile information

Channel Resource

Monitor and manage your Whapi channel settings and health.

Operations

• Check Health: Verify channel operational status
• Get/Update Settings: Manage webhook configurations and channel settings
• Test Webhook: Send test payloads to configured webhooks
• Get Limits: Check API usage limits and quotas

Users Resource

Manage user authentication and profile settings.

Authentication Operations

• Login with QR: Authenticate using QR code (base64, image, or raw data)
• Login with Auth Code: Authenticate using phone number and code
• Logout: Disconnect user session

Profile Management

• Get/Update Profile: Manage user profile information
• Change Status Text: Update WhatsApp status message
• GDPR Operations: Request and manage data reports

Advanced Resources

Stories Resource

• Create and publish WhatsApp stories (text, media, audio)
• Retrieve story lists and details
• Copy existing stories

Statuses Resource

• View message and story read statuses
• Track message delivery and read receipts

Newsletters Resource

• Create and manage WhatsApp channels/newsletters
• Subscribe/unsubscribe from channels
• Manage newsletter content and subscribers

Presences Resource

• Control online/offline presence
• Send typing and recording indicators
• Subscribe to contact presence updates

Error Handling and Best Practices

Robust Error Management

The node implements comprehensive error handling with specific error codes and user-friendly messages:

• Authentication Errors: Clear guidance on credential issues
• Rate Limiting: Automatic retry with exponential backoff
• Validation Errors: Detailed parameter validation with suggestions
• API Errors: Mapped Whapi API errors to actionable messages

Input Validation

All inputs are validated for:

• Phone number format and country codes
• Chat ID format (individual vs group chats)
• URL validation for media files
• Required field enforcement
• Data type validation

Performance Optimization

• Efficient API request handling
• Minimal data transformation overhead
• Proper error propagation
• Memory-conscious data processing

Development and Contributing

Project Structure

whapi-n8n-node-production/
├── credentials/
│   └── WhapiChannelApi.credentials.ts
├── nodes/
│   └── Whapi/
│       ├── actions/
│       │   ├── channel/
│       │   ├── users/
│       │   ├── messages/
│       │   ├── chats/
│       │   ├── contacts/
│       │   ├── presences/
│       │   ├── groups/
│       │   ├── stories/
│       │   ├── statuses/
│       │   └── newsletters/
│       ├── helpers/
│       ├── transport/
│       └── types.ts
├── package.json
├── tsconfig.json
└── README.md

Building from Source

1. Prerequisites:

   • Node.js 18+
   • npm or pnpm
   • TypeScript

2. Development Setup:

   git clone <repository-url>
   cd whapi-n8n-node-production
   npm install
   npm run dev  # Watch mode for development

3. Building:

   npm run build

4. Linting and Formatting:

   npm run lint
   npm run format

Contributing Guidelines

1. Follow TypeScript best practices
2. Maintain comprehensive error handling
3. Add tests for new operations
4. Update documentation for new features
5. Follow the existing code structure and naming conventions

Troubleshooting

Common Issues

Authentication Problems

• Verify API token is correct and active
• Check base URL configuration
• Ensure channel is properly set up in Whapi dashboard

Message Delivery Issues

• Verify phone number format includes country code
• Check if recipient number is registered on WhatsApp
• Ensure media URLs are publicly accessible

Rate Limiting

• Implement delays between bulk operations
• Monitor API usage in Whapi dashboard
• Consider upgrading plan for higher limits

Debug Mode

Enable detailed logging by setting the node to continue on fail and checking error outputs for detailed API responses.

License

MIT License - see LICENSE.md for details.

Support

• Documentation: Whapi.Cloud Docs
• Community: n8n Community Forum
• Issues: GitHub Issues for bug reports and feature requests

Changelog

Version 2.0.1

• Minor package updates and improvements

Version 2.0.0

• Complete rewrite with production-grade architecture
• Added support for all major Whapi API resources
• Implemented comprehensive error handling
• Added TypeScript support throughout
• Enhanced input validation and sanitization
• Improved documentation and examples

Built with ❤️ by Timothy Dake ([email protected]) for the n8n community