Skip to main content
WebsiteGitHub last commitGitHub commit activityGitHub IssuesDocker PullsDiscordLocalized

Messages and Context

Two ideas explain most of how Node-RED works: messages carry data from node to node, and context remembers data between messages. This page covers both.

Messages​

A message is a JavaScript object. Nodes pass messages along wires, and each node can read, change, or replace the message it receives. By convention the main data is in msg.payload, and other properties describe it.

{
"_msgid": "6b8f3a1c2d4e5f60",
"topic": "sensor.kitchen_temperature",
"payload": 71.4
}
PropertyMeaning
payloadThe main data. It can be a string, number, boolean, object, array, or buffer.
topicAn optional label for the message. Some nodes use it to group or route messages.
_msgidA unique ID Node-RED adds so it can follow a message through the flow. Leave it alone.

Nodes add their own properties too. For example, a Home Assistant state node adds msg.data with the event details. Always check a node's Help tab in the sidebar to see what it sets.

Look at a message​

Wire a debug node to the output of any node and deploy. Click a message in the Debug sidebar to expand it and see every property. This is the quickest way to learn what a node really sends.

Read and write properties​

Property names use JavaScript's dot and bracket notation:

ExpressionReads
msg.payloadThe payload.
msg.payload.temperatureA property inside an object payload.
msg.payload[0]The first item of an array payload.
msg["my-property"]A property whose name has characters like - that dot notation can't handle.

In a node's settings you will often see a typed input: a small drop-down next to a field that says what kind of value to use. The common types are:

TypeExampleMeaning
msg.msg.payloadA property of the current message.
flow.flow.modeA value from flow context.
global.global.houseA value from global context.
string, number, booleanonA fixed value.
JSON{"a":1}A fixed object or array.
timestampThe current time, in milliseconds.
env variableTZAn environment variable.
JSONata$now()The result of a JSONata expression, evaluated against the message.

Messages are copied​

If one output is wired to several nodes, each of them gets its own copy of the message. Changing the message in one branch doesn't affect the others, so you don't have to worry about branches interfering.

Context​

A message only lives while it travels through the flow. Context is a store that lasts longer, so you can keep a counter, remember the last value, or share a setting between flows.

Scopes​

ScopeVisible toUse it for
NodeOnly that node.Private state, such as the last value a function node saw.
FlowEvery node on the same tab.Values several nodes on one tab share.
GlobalEvery node on every tab.Settings and values shared across the whole system.

You can read and write context in two places:

  • Function nodes use the context, flow, and global objects. See context and timers.
  • Change and switch nodes can set or test flow. and global. values using a typed input, with no code at all. For example, a change node can set flow.mode to the string away, and a switch node can test it later.

Look at stored values​

Open the Context data tab in the sidebar and press the refresh button for a scope. Seeing the actual stored values is the fastest way to find out why a flow isn't behaving.

Memory and persistent storage​

By default context is kept in memory. It is fast, but the values are lost when Node-RED restarts. It can also be cleared by a deploy, depending on the deploy type and what changed, so don't rely on it for anything you can't recreate.

To keep values across restarts, add a persistent store in settings.js:

contextStorage: {
default: { module: "memory" },
persistent: { module: "localfilesystem" }
},

Restart Node-RED, then name the store when you read or write a value:

flow.set("mode", "away", "persistent");
const mode = flow.get("mode", "persistent");

Values in a file-based store are saved to disk in the Node-RED data folder. Store plain data such as strings, numbers, arrays, and simple objects. Functions and timer handles can't be saved, so keep those in memory.

Home Assistant states are already in context

If you turn on Enable Global Context Store in the Home Assistant server node, the current state of every entity is available in global context. See Home Assistant nodes.

Buy me a beer


💬 Discord Community Chat

Join the conversation! Comments here sync with our Discord community.

💬 Recent Comments

Loading comments...