Package Information
Documentation
n8n-nodes-watsin
This is an n8n community node package for Watsin. It lets you use Watsin in your n8n workflows.
Watsin is an AI assistant for WhatsApp Business. It answers your customers on WhatsApp, Instagram, Messenger, TikTok, email and your website chat, takes orders and bookings, and hands chats to your team when needed. With this package, n8n can react to what happens in Watsin (new messages, leads, orders, payments, bookings) and act on it (send WhatsApp messages, save contacts, pause the AI).
n8n is a fair-code licensed workflow automation platform.
- Installation
- Credentials
- Nodes: Watsin Trigger and Watsin
- Example workflows
- Compatibility
- Development
- Resources
- Version history
Installation
In the n8n editor (self-hosted)
- Go to Settings → Community Nodes.
- Select Install.
- Enter
n8n-nodes-watsinand confirm that you understand the risks of installing unverified code. - Select Install. The Watsin and Watsin Trigger nodes appear in the nodes panel.
Only the instance owner can install community nodes. See n8n's community nodes installation guide.
Manual installation (queue mode, Docker, or no GUI access)
Install the package in n8n's custom nodes folder, then restart n8n:
mkdir -p ~/.n8n/nodes
cd ~/.n8n/nodes
pnpm add n8n-nodes-watsin
With Docker, run the same inside the container (or a volume mounted at /home/node/.n8n/nodes) and restart the container. See n8n's manual installation guide.
Credentials
The nodes use one credential, Watsin API.
| Field | What to enter |
|---|---|
| API Key | Your Watsin API key, starting with wh_. |
| Base URL | https://watsin.net. If your business uses Watsin on its own web address (a white-label domain), enter that address instead, e.g. https://app.yourbrand.com. |
Where to find the API key: in Watsin, open Account → Integrations and go to API key. Select Create key and copy it straight away: it is shown only once. Creating a new key switches the old one off, so update the credential in n8n when you do.
When you save the credential, n8n checks it by calling GET /api/v1/me.
Plan requirements: the trigger needs the Integrations add-on on your Watsin account. The actions work with either Integrations or the Developer API add-on. Without it, Watsin answers 403 and the node shows that the add-on is missing.
Nodes
Watsin Trigger
Starts a workflow the moment something happens in Watsin. When you activate the workflow, the node subscribes a webhook in Watsin for the chosen event; when you deactivate it, the subscription is removed. Each subscription shows up on Watsin's Integrations screen as "n8n:
| Event | Starts the workflow when |
|---|---|
AI Reply Failed (ai.reply_failed) |
The AI didn't answer a customer: out of credits, daily limit reached, or an AI outage |
Booking Cancelled (booking.cancelled) |
An appointment was cancelled |
Booking Created (booking.created) |
A customer booked an appointment |
Contact Created (contact.created) |
Someone wrote to you for the first time |
Conversation Handoff (conversation.handoff) |
The AI asked for a person, the AI was paused, or a team member took the chat |
Lead Captured (lead.captured) |
A visitor on your website chat left their name, phone number or email |
Message Received (message.received) |
A customer wrote to you on WhatsApp, Instagram, Messenger, TikTok, email or your website chat |
Message Sent (message.sent) |
Your AI, you, or the API replied to a customer |
Order Created (order.created) |
A new order from a chat, your website chat or Shopify |
Order Status Changed (order.status_changed) |
An order moved to a new status, e.g. confirmed, shipped, delivered or cancelled |
Payment Received (payment.received) |
A customer paid a Stripe payment link |
Each run outputs one item, the event exactly as Watsin sends it:
{
"id": "evt_3f9c1a7b2d4e6f8a0b1c2d3e",
"type": "order.created",
"created_at": "2026-11-21T09:15:00.000Z",
"account": { "id": 1234, "name": "Cyber Pixel" },
"data": {
"source": "whatsapp_ai",
"order_id": "1042",
"order_number": "1042",
"status": "pending",
"total": 249,
"currency": "AED",
"customer": { "name": "Sara Ahmed", "phone": "971501234567", "email": null },
"items": [{ "name": "Blue dress (M)", "quantity": 1, "price": 249 }],
"channel": "whatsapp"
}
}
The data fields for every event are listed in the Watsin API reference.
Security. Every delivery is signed. Watsin returns a secret when the node subscribes; the node keeps it in the workflow's static data and checks each request's X-Watsin-Signature (HMAC-SHA256 of the timestamp and the raw body) in constant time. Requests with a missing or wrong signature, or a timestamp more than 5 minutes off, get 401 and do not start the workflow.
Good to know
- n8n must be reachable at a public
https://address on port 443. Watsin refuses to send events tohttp://,localhost, private network addresses or other ports. On n8n Cloud this works as is. If you host n8n yourself, setWEBHOOK_URLto your public https address. This also applies to the test URL used by Listen for test event. - Watsin may deliver the same event twice if n8n answered too slowly. Use the event
idto de-duplicate (for example with n8n's Remove Duplicates node). - Events can arrive out of order; use
created_atwhen order matters. - After 20 events in a row fail every retry, Watsin switches the subscription off. Deactivating and re-activating the workflow switches it back on.
Watsin
Acts in Watsin. Every operation works on the account the API key belongs to.
| Resource | Operation | What it does | API |
|---|---|---|---|
| Message | Send | Send a WhatsApp text message, or an approved template on a Cloud API number. Options: Pause AI for this customer, Strict 24-Hour Window (fail instead of falling back to the default template). | POST /send |
| Contact | Create or Update | Create a contact, or update the one with that phone number. A blank name or email never erases the saved one. | POST /contacts |
| Contact | Get Many | Saved contacts, newest first, with an optional Search (name, phone number or email). | GET /contacts |
| Conversation | Get Messages | Recent WhatsApp messages with one contact, newest first. | GET /conversations/:phone/messages |
| AI | Pause | Stop the AI's replies to one customer, the same switch as in the chat screen. | POST /ai/pause |
| AI | Resume | Restart the AI's replies to one customer. | POST /ai/resume |
| Device | Get Many | The account's WhatsApp numbers. | GET /devices |
- Phone numbers are in international format without
+, e.g.971501234567. Spaces, dashes and a leading+are removed for you. - WhatsApp Number (on Send, Pause and Resume) is a dropdown of your numbers. Leave it empty when the account has one connected number; it is required when there are several.
- Get Many operations have Return All and Limit (default 50). The node follows Watsin's pages for you.
- The node can be used as a tool by n8n's AI Agent.
- Watsin allows 300 requests a minute per API key. Above that it answers
429; use n8n's Retry On Fail setting or a Wait node for large batches.
Example workflows
Import any of these from the examples/ folder (in n8n: Workflows → Import from File), then select your Watsin credential on the Watsin nodes.
| File | What it does |
|---|---|
examples/new-whatsapp-message-to-google-sheets.json |
New WhatsApp message → Google Sheets row. Message Received trigger, keeps WhatsApp messages only, and appends Time, Name, Phone, Message, Number and Event ID to a sheet called "Messages". Set your spreadsheet URL and Google credential. |
examples/new-order-to-slack.json |
New order → Slack message. Order Created trigger, then posts the order number, customer, total and items to #orders. Set your Slack credential and channel. |
examples/new-lead-whatsapp-welcome.json |
New lead → WhatsApp welcome. Lead Captured trigger, keeps leads that left a phone number, saves them as a contact, and sends a WhatsApp welcome message. The number is what the visitor typed and is not verified, so keep the welcome short and friendly. |
Compatibility
- Tested on n8n 2.48.7 (
n8nNodesApiVersion1). Older versions have not been tested. - Development needs Node.js 22 or later. At runtime the package uses whatever Node.js version your n8n runs on.
- No runtime dependencies.
- Works with Watsin API v1 (
https://watsin.net/api/v1, or your own Watsin domain).
Development
This package was scaffolded with @n8n/node-cli and uses pnpm.
pnpm install
pnpm lint # n8n's community node linter
pnpm build # compiles to dist/
pnpm test # unit tests (vitest), no network
pnpm dev # runs n8n locally with this package loaded
Scan the build with the same checks n8n runs before verification:
pnpm build
pnpm dlx @n8n/scan-community-package .
Releases are published to npm by GitHub Actions with a provenance statement (see .github/workflows/publish.yml). Push a tag like v0.1.0 that matches the version in package.json.
Resources
- n8n community nodes documentation
- Watsin
- Watsin API reference: in Watsin, Account → Integrations shows the API base URL, your key and the full event reference.
Version history
See CHANGELOG.md.