Overview
The Whaapy n8n node allows you to integrate WhatsApp automation into your n8n workflows. You can send messages, manage conversations, control AI agents, and receive webhook events.
Installation
From npm
- Open your n8n instance
- Go to Settings → Community Nodes
- Click Install a community node
- Enter
n8n-nodes-whaapy
- Click Install
Manual Installation
# Navigate to your n8n custom nodes directory
cd ~/.n8n/custom
# Install the package
npm install n8n-nodes-whaapy
# Restart n8n
Authentication
- Go to app.whaapy.com → Settings → API Keys
- Create a new API key
- In n8n, go to Credentials → New Credential
- Search for Whaapy API
- Enter your API key (starts with
wha_)
Available Operations
Message
| Operation | Description |
|---|
| Send | Send a WhatsApp message (text, image, video, audio, document, template, interactive, location, contacts, sticker, reaction) |
| Retry | Retry a failed message |
| Operation | Description |
|---|
| Upload | Upload media to WhatsApp CDN |
Conversation
| Operation | Description |
|---|
| List | Get all conversations |
| Get | Get a specific conversation |
| Get by Phone | Find conversation by phone number |
| Get Messages | Get message history |
| Close | Close a conversation |
| Archive | Archive a conversation |
| Mark Read | Mark as read |
| Set AI | Enable/disable AI for conversation |
| Pause AI | Pause AI temporarily |
| AI Suggest | Get AI suggestion without sending |
Agent
| Operation | Description |
|---|
| Toggle | Enable/disable AI globally |
| Pause | Pause AI globally for X minutes |
Template
| Operation | Description |
|---|
| List | Get all WhatsApp templates |
| Get | Get a specific template |
| Get Variables | Get available template variables |
| Sync | Sync templates from Meta |
| Operation | Description |
|---|
| List | Get all contacts |
| Get | Get a specific contact |
| Create | Create a new contact |
| Update | Update a contact |
| Delete | Delete a contact |
| Search | Advanced search |
| Bulk | Bulk operations |
| Merge | Merge two contacts |
| Get Tags | Get all tags |
| Get Fields | Get custom fields |
Funnel
| Operation | Description |
|---|
| List Stages | Get all funnel stages |
| Get Stage | Get a specific stage |
| Create Stage | Create a new stage |
| Update Stage | Update a stage |
| Delete Stage | Delete a stage |
| Reorder Stages | Reorder stages |
| Move Contact | Move contact to stage |
Trigger Node
The Whaapy Trigger node listens for webhook events:
| Event | Description |
|---|
message.received | Incoming message |
message.sent | Message sent |
message.delivered | Message delivered |
message.read | Message read |
message.failed | Message failed |
conversation.created | New conversation |
conversation.updated | Conversation updated |
conversation.handoff | Handoff to human |
* | All events |
This event fires only when a new conversation is created—i.e., when a contact writes for the first time, or when you send the first message to a new number via the API. To test it, use a WhatsApp number that has never initiated a conversation with your business. If the contact already has a chat history, you won’t see this event; use message.received instead for per-message triggers.
Example Workflows
Send Welcome Message
Webhook (receive lead) → Whaapy (Send template) → Slack (Notify team)
Auto-Response with AI Control
Whaapy Trigger (message.received) → IF (contains "human") → Whaapy (Pause AI) → Slack (Assign agent)
CRM Integration
Whaapy Trigger (message.received) → HTTP Request (CRM API) → Whaapy (Update contact tags)
Funnel Automation
Whaapy Trigger (conversation.created) → Whaapy (Move Contact to stage) → Whaapy (Send welcome template)
Tips
Pausing AI for Manual Intervention
When sending a manual message, use the Pause AI option to prevent the AI from responding:
{
"to": "+5215512345678",
"type": "text",
"content": "I'll handle this personally",
"additionalFields": {
"pauseAi": true,
"pauseDuration": 30
}
}
Using Templates
Templates are required for messaging outside the 24-hour window. Get your templates first:
- Use Template → List to see available templates
- Use the template name in Message → Send
{
"to": "+5215512345678",
"messageType": "template",
"templateName": "welcome_message",
"templateParameters": ["John", "Acme Corp"]
}
By default, Whaapy uses the quick-reply IDs configured in your business template. In the n8n node you can enable Allow Button Payload Override and send a JSON map in Quick Reply Payload Overrides (for example { "0": "confirm_order", "1": "talk_to_agent" }) only when you need per-workflow overrides.
For template headers with media, use Template Options:
- Header Media Source = URL + Header Media URL for public files.
- Header Media Source = Media ID + Header Media ID when you already uploaded the media to Meta.
If you receive MEDIA_PERMISSION_DENIED, the media_id was uploaded with a different token/WABA/number than the sender.
- Upload media first using Media → Upload
- Use the returned
media_id in your message
Resources
