watsin

n8n nodes for Watsin: send WhatsApp messages, manage contacts, pause the AI and trigger workflows on new messages, leads, orders, payments and bookings.

Package Information

Released: this month
Downloads: 0 weekly / 0 monthly
Latest Version: 0.1.0
Author: Syed Shehzad Gillani

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

In the n8n editor (self-hosted)

  1. Go to Settings → Community Nodes.
  2. Select Install.
  3. Enter n8n-nodes-watsin and confirm that you understand the risks of installing unverified code.
  4. 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 to http://, localhost, private network addresses or other ports. On n8n Cloud this works as is. If you host n8n yourself, set WEBHOOK_URL to 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 id to de-duplicate (for example with n8n's Remove Duplicates node).
  • Events can arrive out of order; use created_at when 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 (n8nNodesApiVersion 1). 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

Version history

See CHANGELOG.md.

License

MIT

Discussion