Skip to content

Turbo Notify in Node-RED

The Turbo Notify nodes for Node-RED send WhatsApp messages from your own number (text, images, video, audio, documents, stickers, locations and replies), read how far a message has got, and start a flow when something happens on your number, such as a message arriving. A sensor, a schedule or any other node in a flow can become a message.

  • A Turbo Notify account with a connected number (quickstart).
  • Node-RED 3.0.0 or later, on Node.js 18 or later.
  • An API key, created in API Keys (opens in a new tab) with the AI agent (MCP) template, which covers sending, reading messages, reading numbers (so Test can check that your number is linked) and reading events. Scopes are in Access key.
  1. Install the package. In Node-RED, open the menu, choose Manage palette, then Install, and search for @turbo-notify/node-red-whatsapp. Or, in your Node-RED user directory (usually ~/.node-red):

    npm install @turbo-notify/node-red-whatsapp

    Restart Node-RED. The nodes appear in the Turbo Notify category of the palette: whatsapp send, whatsapp status and whatsapp events.

  2. Drag a whatsapp send node into a flow and double-click it. Next to Account, click the +: the dialog repeats the three things you need (account, WhatsApp number linked, API key) with links to each screen of the dashboard.

  3. Paste your key and press Test. It tells you in plain words whether the key works and whether your WhatsApp number is linked, and what to do if not (a button opens the right page of the dashboard). Click Add.

  4. In To, put your own phone number in international format (+5511988887777).

  5. Wire an inject node with a text payload to the send node and deploy. If you deploy before pasting a key, the node shows a yellow paste your API key instead of failing on the first message.

Node-RED signs in with the API key. The key is kept in Node-RED’s credentials store, so it never appears in the flow file or in an exported flow, and it is sent only to Turbo Notify, over https. The address of the API is not a setting of a flow, so a flow you import or share cannot choose where your key goes.

Press the inject button. The node accepts the message at once and WhatsApp delivers it a moment later. To follow it, wire a whatsapp status node after the send: it reads the message id the send node leaves in msg.messageId and returns pending, sent, delivered, read or failed.

To start a flow when a message arrives, use the whatsapp events node. By default it listens to message.received, checks every 30 seconds and emits one message per event, with the whole event in msg.payload and its type in msg.topic. The first check after a deploy only remembers the newest message, so messages that arrived before the deploy do not start the flow. To test, deploy, write to your number from another phone and wait up to 30 seconds. A message that quotes another one arrives as message.replied: the answering examples listen to both types, and you can write message.received,message.replied in the Event types field of your own flows.

Eighteen flows are ready to import: in the menu, Import, then Examples, then @turbo-notify/node-red-whatsapp. Each starts with a note called START HERE that repeats the three setup steps and says what to change. Replace the placeholder number (+12025550123) before you deploy, in the flows that have one. The flows that answer people reply to whoever wrote, so they have none; the team group flow has a placeholder group id to replace.

  • Alerts from things: a door sensor, a temperature that goes above a limit (one message when it does, one when it is back to normal), a website that goes down (one message when it fails, one when it recovers), an error in Node-RED itself, and a picture from a camera.
  • Scheduled messages: a reminder on weekdays, a daily report to a list of people (one message every 10 seconds), and today’s weather forecast every morning.
  • Messages from your systems: an HTTP endpoint that sends a message when another system calls it, protected by a token, and an order confirmation that writes a summary for the customer.
  • Answering people: a reply to every private message (at most one an hour for each person), a menu that answers 1, 2 or 3, an after-hours reply sent at most once every 12 hours to each person, a map location when someone asks where you are, and forwarding of private messages to a team group (at most 5 an hour from one person and 20 in all).
  • Documents and checks: a PDF with a caption, a delivery check that warns you if a message failed, and a CSV log of every message you receive.

In Manage palette, open the Nodes tab and update the package, or run npm update @turbo-notify/node-red-whatsapp in your Node-RED user directory and restart.

If you installed the first version, @turbo-notify/node-red-turbo-notify, uninstall it and install @turbo-notify/node-red-whatsapp. The nodes did not change, so your flows keep working.

  • Your number sends one message at a time, a few seconds apart. A message that waits more than 5 minutes fails with message_timeout (it may still arrive), so a flow that sends a long list can lose the last messages. A send that comes sooner than the minimum gap of the plan (6 seconds on Free, see Rate limits) is refused with 429 send_rate_spacing. A flow that sends a list should put a delay node set to rate limit (one message every 10 seconds) in front of the send node, as the daily report example does.
  • A cycle is one month of your subscription, and each number has a message and a contact allowance per cycle (Free: 300 messages and 2 contacts, see Quota and usage). When a limit is reached nothing is sent silently: the send is refused with messages_quota_exceeded (or contact_quota_exceeded for a new contact), the node raises that error with the code, and a Catch node can react, for example by sending you an e-mail. Sending works again when the cycle turns or right after a change to a bigger plan. The Test button of the account node shows what you have used and when the count starts again.
  • Which number: one that already has WhatsApp on a phone. Turbo Notify links it the way WhatsApp Web does, with a QR code or a pairing code, and does not create the account. A SIM card in a router or modem works if you can register WhatsApp on it (see Numbers).
  • Events are polled, not pushed: every 30 seconds by default, never faster than every 10. Delivery is at least once, so keep msg.payload.id if a flow must never act twice on the same event. After a restart, Node-RED’s default in-memory context starts again from now; to keep the position across restarts, set a persistent context store in settings.js.
  • Media is sent from a public https address. Node-RED does not upload a file.
  • Sending to a group needs the Business plan or higher.
  • What was run: the nodes were loaded and exercised in the Node-RED Docker images 3.0.2, 3.1.15, 4.1.17 and 5.0.9 against a stand-in for the API, and on 12 November 2026 the package, installed from npm into Node-RED 4.1.17, was used with a real key: the account node’s Test button passed, one message was sent and reached delivered, and the events node received the message.sent event. The editor screens of version 1.5.15 (the account dialog, the states of the Test button and the START HERE note) were walked through in a real Node-RED 4.1 editor against the stand-in for the API. Not run: those screens with a real key.