node-red-contrib-whatsapp-api

Node-RED nodes for driving a WhatsApp Web session with Baileys.

What it includes

• whatsapp-api-config: stores reconnect settings and the local runtime data directory
• whatsapp-api-in: emits normalized incoming WhatsApp messages
• whatsapp-api-send: sends text or media to a chat
• whatsapp-api-history: reads recent messages from the local persisted store

Runtime requirements

• Node.js 20+
• Node-RED 4+
• A phone that can scan the WhatsApp Web QR code

Install locally

npm install
npm run build
cd ~/.node-red
npm install /absolute/path/to/node-red-contrib-whatsapp-api-0.1.0.tgz

Then restart Node-RED and add the whatsapp-api nodes from the palette.

The packed module ships as a bundled runtime, so target installs do not need to rebuild or reshuffle the Baileys dependency tree on the Node-RED host.

Install from npm

After the package has been published:

cd ~/.node-red
npm install node-red-contrib-whatsapp-api

Login flow

This palette uses a deploy-first QR flow.

1. Add a whatsapp-api-config node and deploy the flow.
2. Open the config node again in the editor.
3. Click Connect.
4. Scan the QR code with WhatsApp on your phone.
5. Wait for the status to show Connected.

The runtime keeps its auth state on disk and now attempts to reuse it automatically after every Node-RED restart. Use Disconnect to clear the stored session and force a fresh QR login.

Local message history

whatsapp-api-history reads from a local JSON store that is updated by the connected runtime. It returns messages the session has already synced or seen. It is not a server-side fetch of arbitrary WhatsApp chat history.

The history node can also return only the newest incoming messages that the linked WhatsApp account still has unread for the selected chat.

Example Node-RED flow

Import this JSON from the Node-RED editor (Menu -> Import -> Clipboard) to get a starter flow with:

• one whatsapp-api-config node
• one whatsapp-api-send example
• one whatsapp-api-in listener
• one whatsapp-api-history example

Replace the sample peer with a real WhatsApp JID such as [email protected].

[
  {
    "id": "a1f4d7c2e9b00101",
    "type": "tab",
    "label": "WhatsApp Example",
    "disabled": false,
    "info": ""
  },
  {
    "id": "b2f4d7c2e9b00102",
    "type": "whatsapp-api-config",
    "name": "My WhatsApp",
    "reconnectMinMs": "2000",
    "reconnectMaxMs": "30000",
    "dataDir": ""
  },
  {
    "id": "c3f4d7c2e9b00103",
    "type": "inject",
    "z": "a1f4d7c2e9b00101",
    "name": "Send test message",
    "props": [
      {
        "p": "payload"
      }
    ],
    "payload": "hello from Node-RED",
    "payloadType": "str",
    "x": 170,
    "y": 100,
    "wires": [
      [
        "d4f4d7c2e9b00104"
      ]
    ]
  },
  {
    "id": "d4f4d7c2e9b00104",
    "type": "whatsapp-api-send",
    "z": "a1f4d7c2e9b00101",
    "name": "Send WhatsApp",
    "account": "b2f4d7c2e9b00102",
    "peer": "[email protected]",
    "x": 450,
    "y": 100,
    "wires": [
      [
        "e5f4d7c2e9b00105"
      ]
    ]
  },
  {
    "id": "e5f4d7c2e9b00105",
    "type": "debug",
    "z": "a1f4d7c2e9b00101",
    "name": "Send result",
    "active": true,
    "tosidebar": true,
    "complete": "true",
    "targetType": "full",
    "x": 720,
    "y": 100,
    "wires": []
  },
  {
    "id": "f6f4d7c2e9b00106",
    "type": "whatsapp-api-in",
    "z": "a1f4d7c2e9b00101",
    "name": "Incoming messages",
    "account": "b2f4d7c2e9b00102",
    "includeRaw": false,
    "x": 190,
    "y": 200,
    "wires": [
      [
        "07f4d7c2e9b00107"
      ]
    ]
  },
  {
    "id": "07f4d7c2e9b00107",
    "type": "debug",
    "z": "a1f4d7c2e9b00101",
    "name": "Incoming debug",
    "active": true,
    "tosidebar": true,
    "complete": "true",
    "targetType": "full",
    "x": 470,
    "y": 200,
    "wires": []
  },
  {
    "id": "18f4d7c2e9b00108",
    "type": "inject",
    "z": "a1f4d7c2e9b00101",
    "name": "Read last 5",
    "props": [
      {
        "p": "payload"
      }
    ],
    "payload": "",
    "payloadType": "date",
    "x": 150,
    "y": 300,
    "wires": [
      [
        "29f4d7c2e9b00109"
      ]
    ]
  },
  {
    "id": "29f4d7c2e9b00109",
    "type": "whatsapp-api-history",
    "z": "a1f4d7c2e9b00101",
    "name": "Recent Chat History",
    "account": "b2f4d7c2e9b00102",
    "peer": "[email protected]",
    "limit": "5",
    "includeRaw": false,
    "x": 450,
    "y": 300,
    "wires": [
      [
        "3af4d7c2e9b0010a"
      ]
    ]
  },
  {
    "id": "3af4d7c2e9b0010a",
    "type": "debug",
    "z": "a1f4d7c2e9b00101",
    "name": "History debug",
    "active": true,
    "tosidebar": true,
    "complete": "true",
    "targetType": "full",
    "x": 730,
    "y": 300,
    "wires": []
  }
]

Message contract

Incoming and action nodes use this shape:

• msg.payload: the main payload for the node
• msg.whatsapp: normalized WhatsApp metadata

Common metadata fields:

• msg.whatsapp.peer: { id, type, title, ref }
• msg.whatsapp.chatId
• msg.whatsapp.senderId
• msg.whatsapp.messageId
• msg.whatsapp.media
• msg.whatsapp.raw when the node is configured with Include Raw

Send node input patterns

Text only:

{
  "payload": "hello from Node-RED",
  "whatsapp": {
    "peer": "[email protected]"
  }
}

Media with a file path:

{
  "payload": "daily report",
  "whatsapp": {
    "peer": "[email protected]",
    "mediaPath": "/tmp/report.pdf"
  }
}

Media with a Buffer:

msg.payload = Buffer.from("file-bytes");
msg.whatsapp = {
  peer: "[email protected]",
  fileName: "image.jpg",
  caption: "generated by a flow",
  mimeType: "image/jpeg"
};
return msg;