Understanding and Using The Node-Red Message Object

A 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 or parts depending on 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 (complete message object).


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


You will see that is has the following properties or parts

  • 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-red 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:


Adding Properties 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.

Common Errors

When working with the message object you will probably encounter some of the following errors:

  • function tried to send a message of type number node red
  • function tried to send a message of type string node red

Both are caused by assigning a string or number to the message object instead of assigning an object e.g

msg="This is invalid";

Another common mistake is to delete the existing msg properties or not forward them on to the next node.

return msg;

The following is valid but all the properties in the original msg object are lost to the following node.

return msg1;

Msg Object and The Node-Red 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:

Click to rate this post!
[Total: 3 Average: 5]


  1. Hi Steve,
    thanks for your immense contribution.
    I’m trying to transfer a csv file, I can, but the only thing is that I can’t send the “msg.filename”. it is as if the MQTT OUT node is blocking the msg.filename property. In fact, in the MQTT IN node I do not receive this property but only PAYLOAD, TOPIC, RETAIN; QOS; MsgID. I would be really grateful if you could give me some indication.

    1. The mqtt node doesn’t take the filename only retain,qos,topic and payload.
      If you take a look at my python example you will need to do the same with node-red.

      The code keeps the file in binary and send the filename in a binary header. Working in bytes in python is straight forward but not so in Javascript.
      another approach would be to use the IBM approach (linked in the article) to Base64 encode the binary data so it is sent as text.
      If you struggle with it let me know and I’ll try doing it myself it is on my long list of things to do.

      1. Hi Steve,
        I have found a different solution, I don’t know if it is correct but it works. I send to the MQTT OUT node (with a FUNCTION node) the filename immediately after the “\” character, in the TOPIC property, for example the TOPIC is “Test \ filename” and after the MQTT node IN use a FUNCTION node to extract the “filename” from the TOPIC property received with the SUBSTR function (javascript function).
        Thank you for your answer.

        1. Rob
          That will work but the subscriber has to know the topic in advance.MQTTv5 lets you send additional data other than in the payload and will make this much easier.

  2. I am using the contrib_ftp node (https://flows.nodered.org/node/node-red-contrib-ftp) and it requires a file name to work (if I put a value in there it creates a file on the ftp server). Problem is I need this file to be dynamic as I have a file name from a previous output which is the “watch” node over a file location I want to push to FTP. How do you pass the msg.filename from the watch node to the FTP node as ive tried leaving it blank and tried msg.filename and it just either errors as no file name or creates a file called msg.filename?

    1. Hi
      From the docs it looks like you use
      msg.LocaLFilename for files on the node-red server and
      msg.filenane for the files on the ftp server.
      Let me know if it works.
      Note pay attention to the uppercase letters in the name

      1. thanks, im new to node red, here is the output of the previous node.


        In the LocalFilename ive got the value of “/home/pi/Pictures/”

        and when I use “msg.filename” or “=msg.filename” in the Filename field it just creates a file called msg.filename or =msg.filename in the “/FTP” directory I need. Do I need to type something else to pass the file over

  3. 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?

  4. 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)

    1. Can you send me the current flow you have and I’ll look at it.It doesn’t matter if it isn’t working

  5. 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


  6. 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.

  7. 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 *