npm package: @joaopauloqueiroz/n8n-nodes-whatsapp-api
Description: n8n nodes to integrate with WhatsApp API Manager
Author: ArchCode
Latest version: 1.1.0

# n8n-nodes-whatsapp-api

Custom n8n nodes for integrating with WhatsApp API Manager. Automate your WhatsApp workflows with powerful nodes for sending messages, managing sessions, labels, and webhooks.

## 📦 Installation

### Option 1: Install from npm (Recommended)

```bash
npm install n8n-nodes-whatsapp-api
```

### Option 2: Manual Installation

1. Clone this repository
2. Navigate to the project directory
3. Build the project:
   ```bash
   npm install
   npm run build
   ```
4. Link to your n8n installation:
   ```bash
   npm link
   cd ~/.n8n
   npm link n8n-nodes-whatsapp-api
   ```

### Option 3: Docker

If you're using n8n with Docker, mount the built nodes:

```bash
docker run -it --rm \
  --name n8n \
  -p 5678:5678 \
  -v ~/.n8n:/home/node/.n8n \
  -v /path/to/n8n-nodes-whatsapp-api/dist:/home/node/.n8n/custom \
  n8nio/n8n
```

## 🔐 Credentials Setup

1. In n8n, go to **Credentials** → **New**
2. Search for "WhatsApp API"
3. Configure:
   - **API URL**: Your WhatsApp API base URL (e.g., `http://localhost:3001`)
   - **API Token**: Your JWT authentication token
4. Click **Test** to verify the connection
5. Save the credentials

## 📚 Available Nodes

### 1. WhatsApp API Trigger

Receive WhatsApp messages and events via webhook.

**Features:**
- Real-time message reception
- Event filtering (received, sent, delivered, read, QR updates, etc.)
- Automatic webhook registration

**Example Use Cases:**
- Auto-respond to customer messages
- Log all incoming messages
- Trigger workflows based on keywords

### 2. WhatsApp API - Send Message

Send various types of messages through WhatsApp.

**Message Types:**
- **Text**: Simple text messages with formatting
- **Image**: Send images with optional captions
- **Video**: Send video files
- **Audio**: Send audio/voice messages
- **Document**: Send PDF and other documents
- **Buttons**: Interactive messages with up to 3 buttons
- **Bulk**: Send to multiple recipients

**Features:**
- Media support (URL or base64)
- Label assignment
- Bulk sending with delay control
- Rich text formatting

**Example Use Cases:**
- Send promotional messages
- Share documents with customers
- Create interactive menus with buttons
- Bulk notifications

### 3. WhatsApp API - Session

Manage WhatsApp sessions (connections).

**Operations:**
- Create Session
- Get Session Details
- List All Sessions
- Start Session
- Stop Session
- Delete Session

**Example Use Cases:**
- Initialize new WhatsApp connections
- Monitor session status
- Manage multiple WhatsApp accounts
- Auto-restart disconnected sessions

### 4. WhatsApp API - Labels

Manage WhatsApp Business labels for organization.

**Operations:**
- Create Label (20 colors available)
- Get All Labels
- Delete Label
- Apply Label to Chat
- Remove Label from Chat
- Get Chat Labels

**Example Use Cases:**
- Organize conversations by category
- Tag important customers
- Filter chats by label
- Automated labeling based on message content

### 5. WhatsApp API - Webhook

Manage webhook configurations.

**Operations:**
- Register Webhook
- List Webhooks
- Toggle Webhook (enable/disable)
- Delete Webhook
- Get Webhook Logs
- Test Webhook

**Example Use Cases:**
- Configure multiple webhook endpoints
- Monitor webhook delivery
- Debug webhook issues
- Manage event subscriptions

## 🚀 Example Workflows

### Auto-Reply Bot

```
WhatsApp Trigger → IF (contains keyword) → Send Message
```

1. Add **WhatsApp API Trigger** node
2. Add **IF** node to check message content
3. Add **WhatsApp API - Send Message** node to reply

### Customer Support Labeling

```
WhatsApp Trigger → Analyze Message → Apply Label
```

1. Receive message via **WhatsApp API Trigger**
2. Process/analyze content (AI, keywords, etc.)
3. Use **WhatsApp API - Labels** to categorize

### Bulk Campaign

```
Spreadsheet → Loop → Send Message (with delay)
```

1. Load contacts from spreadsheet
2. Use **WhatsApp API - Send Message** in bulk mode
3. Add delay to avoid rate limits

### Session Monitor

```
Schedule Trigger → List Sessions → IF (disconnected) → Start Session
```

1. Run every 5 minutes with **Schedule Trigger**
2. Get all sessions with **WhatsApp API - Session**
3. Check status and restart if needed

## 🛠️ Development

### Prerequisites

- Node.js 18+
- npm or yarn
- n8n installed (globally or locally)

### Setup

```bash
# Clone the repository
git clone https://github.com/joaopauloqueiroz/whatsapp-api.git
cd whatsapp-api/n8n-nodes-whatsapp-api

# Install dependencies
npm install

# Build in watch mode
npm run dev
```

### Testing Locally

```bash
# Build the project
npm run build

# Link to n8n
npm link

# In your n8n directory
npm link n8n-nodes-whatsapp-api

# Start n8n
n8n start
```

Your custom nodes will appear in n8n under the "Custom" category.

### Project Structure

```
n8n-nodes-whatsapp-api/
├── credentials/
│   └── WhatsAppApi.credentials.ts    # Authentication
├── nodes/
│   ├── WhatsAppApiTrigger/
│   │   └── WhatsAppApiTrigger.node.ts
│   ├── WhatsAppApiSendMessage/
│   │   └── WhatsAppApiSendMessage.node.ts
│   ├── WhatsAppApiSession/
│   │   └── WhatsAppApiSession.node.ts
│   ├── WhatsAppApiLabels/
│   │   └── WhatsAppApiLabels.node.ts
│   └── WhatsAppApiWebhook/
│       └── WhatsAppApiWebhook.node.ts
├── package.json
├── tsconfig.json
└── gulpfile.js
```

## 📖 API Reference

This package integrates with [WhatsApp API Manager](https://github.com/joaopauloqueiroz/whatsapp-api).

**Required API Endpoints:**
- `POST /api/sessions` - Create session
- `GET /api/sessions` - List sessions
- `POST /api/messages/:sessionId/send` - Send message
- `GET /api/labels/:sessionId/labels` - Get labels
- `POST /api/webhooks` - Register webhook

For full API documentation, see the main project README.

## 🐛 Troubleshooting

### Nodes not appearing in n8n

1. Ensure the package is properly linked: `npm link n8n-nodes-whatsapp-api`
2. Restart n8n
3. Check n8n logs for errors

### Authentication errors

1. Verify your API URL is correct (include `http://` or `https://`)
2. Check that your JWT token is valid
3. Test credentials using the "Test" button

### Webhook not receiving events

1. Ensure your n8n instance is publicly accessible
2. Check webhook URL in the WhatsApp API dashboard
3. Verify event types are correctly configured

### Build errors

```bash
# Clean and rebuild
rm -rf dist node_modules
npm install
npm run build
```

## 📝 License

MIT License - see [LICENSE](../LICENSE) file for details.

## 🤝 Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Test thoroughly
5. Submit a pull request

## 🔗 Links

- [Main WhatsApp API Project](https://github.com/joaopauloqueiroz/whatsapp-api)
- [n8n Documentation](https://docs.n8n.io/)
- [n8n Community Nodes](https://docs.n8n.io/integrations/community-nodes/)

## 💬 Support

- Open an issue on GitHub
- Check existing issues for solutions
- Refer to the main project documentation

## ⭐ Credits

Created by **ArchCode**

Built with:
- [n8n](https://n8n.io/) - Workflow automation
- [WhatsApp Web.js](https://github.com/pedroslopez/whatsapp-web.js) - WhatsApp client

---

**Made with ❤️ for the n8n community**