Understanding The Node-Red Message Object

node-red-icon1A node red flow consists of a series of interconnected nodes.(wired nodes).

All nodes must have an input and can have 0 or multiple outputs.

Nodes exchange data between each other using the msg object.

Each node receives the message object from the previous node, and can then pass this message object onto the next node in the flow.

The Msg Object

The Msg Object is a standard JavaScript object and has several existing properties depending where it originated.

You can see the message properties by sending the msg to the debug node.


By default the debug node will display the msg.payload property but you can edit the debug node to display all of the message properties.


If you Look at the message object properties of the the inject node.

inject-node message object

You will see that is has the following properties

  • payload
  • topic
  • _msgid

A msg object that originates from an MQTT input node has the following properties:

  • payload
  • topic
  • qos
  • _msgid
  • retain

as shown in the screen shot below:


The _msgid property is a message identifier added by node read and can be used to track message objects.

Msg object properties can be any valid JavaScript type e.g.

  • String
  • Integer
  • Object
  • Boolean

Modifying the msg Object

Node-red provides various core nodes that can change the messages object without you having to write any JavaScript code.

The main nodes are change, split, join, switch

You can find out more of what they do by dragging them onto the flow and then viewing the info tab associated with them.


See the documentation for more details

There is also the very versatile function node, but using it requires writing JavaScript code.

Accessing the msg Properties

You access the msg properties just like you do any JavaScript object.

The message payload can be accessed using:

var payload=msg.payload;

and can be modified using:


Likewise the message topic can be accessed using:

var topic=msg.topic;

and can be modified using:

msg.topic= topic;

If you are using a node like the change node then it defaults to payload but you can change any property by editing the appropriate field as shown below:

msg-change node-example

Adding to the msg Object

You can add properties to the message object. For example if you had an object containing sensor values that looked like this:


You can add it to msg object using


It will be passed on to the next node along with the existing msg properties.

Msg Object and Function Node

Using the function node gives you a better understanding of the node-red msg object see –Using the Node-Red Function Node- Beginners Guide


An Introduction to the Node-Red msg Object

<=====How to Export and Import Nodes and Flows

=====>How to Create a Basic Node-Red Dashboard


Related Tutorials:

Please rate? And use Comments to let me know more
[Total: 7    Average: 3.4/5]


  1. First of all thank you very much for you excellent articles.

    I have the following scenarion. The MQTT payload for a topic that I subscribed for looks like this:


    I would like to display these 2 values in 2 gauges on a node-red dashboard. How can this be achieved?

  2. Hey steve!
    I am currently getting an object as a payload with 63 various values from various sensors.The number of parameters is also dynamic as if i add more sensors then the payload object size increases.Is there any way to declare a variable that would be of undefined size and then dynamically allocates the size every time so that i need no code every single time when a sensor is added and also I have to take each and every parameter value from the payload and write a function that compares it with it’s upper and lower limits and then produce an output.Could you please help me with how to write the code for this application as I am totally new to the platform.I have no clue on how to retrieve the data from the payload object and then write a function which can be adopted by all parameters….An excel sheet would also contain the parameters, their upper and lower limits but the values from parameters are obtained rea-time(maybe this might help you in providing a solution)

  3. Hi there,
    just wonder if I also could expand the msg.payload with additional properties. Like a temp Sensor should become a field Temperatur and the value. So kind of msg.payload.temperatur. How do I code this

    1. yes use

      msg.data and
      if you use the msg payload then you would need to do something like this
      payload=msg.payload //save the original payload
      newpayload={“temperature”:20,”humidity”:80,”payload”:payload} //create a new payload
      msg.payload=newpayload //save it back


  4. Figuring out all the various data formats has been my brick wall in making Node-Red to work for me in my home IOT. Your discussion here told me more than a month of experimenting on my own has. Thanks.

    Hope you can help me figure this out.
    I have an Alexa Local node that responds to a voice command with an object. For example “Alexa, turn on kitchen light 50%” responds with this:
    “device_name”:”Kitchen Light”,

    I need to send this data (Well, not all of it, just the “payload” of ‘on’ or ‘off’ and the “bri” value) to another Raspberry Pi using MQTT. But, MQTT only passes “Payload”. How can I put the data into the payload? I assume a function to “encode” it on the sending end and another function to “Decode” it at the receiving end, but is there an easier way that you can think of?


    1. Glad you found it useful.
      As for your problem. I assume that the object is the payload object. If s you pass it into a function node and strip out the payload and brightness and maybe extract the device name for the topic.
      If that is the case then let me know and I’ll write the function node if you want. Use the ask steve page to send me the details.

  5. Hi Steve,
    I am new to Node-RED and the whole IOT arena. I have become interested in home automation / security as a hobby and had been struggling with counting bursts of messages from multiple sources. I had not been able to solve my problem till I stumbled on your web site.

    I read your articles on storing variables and Understanding The Node-Red Message Object in Node-RED and 15 minutes later I have what I want working and graphing the messages from each source.

    In my limited opinion your explanations were very clear and concise with sufficient supporting code to make extrapolation logical. They also happened to be very specific to my problem.

    Thank you very much.
    I will read more of your articles as all the topics are on interest.
    Rick Craig

Leave a Reply

Your email address will not be published. Required fields are marked *