Retained Messages - MQTT Essentials: Part 8

Written by The HiveMQ Team

Category: MQTT Essentials MQTT

Published: March 2, 2015


Welcome to the eighth part of MQTT Essentials. A ten-part blog series on the core features and concepts of the MQTT protocol. This post introduces retained messages.

In MQTT, the client that publishes a message has no guarantee that a subscribing client actually receives the message. The publishing client can only make sure that the message gets delivered safely to the broker. Basically, the same is true for a subscribing client. The client that connects and subscribes to topics has no guarantee on when the publishing client will publish a message in one of their topics of interest. It can take a few seconds, minutes, or hours for the publisher to send a new message in one of the subscribed topics. Until the next message is published, the subscribing client is totally in the dark about the current status of the topic. This situation is where retained messages come into play.

Retained Messages

A retained message is a normal MQTT message with the retained flag set to true. The broker stores the last retained message and the corresponding QoS for that topic. Each client that subscribes to a topic pattern that matches the topic of the retained message receives the retained message immediately after they subscribe. The broker stores only one retained message per topic.

If the subscribing client includes wildcards in the topic pattern they subscribe to, it receives a retained message even if the topic of the retained message is not an exact match. Here’s an example: Client A publishes a retained message to myhome/livingroom/temperature. Sometime later, client B subscribes to myhome/#. Client B receives the myhome/livingroom/temperature retained message directly after subscribing to myhome/#. Client B (the subscribing client) can see that the message is a retained message because the broker sends retained messages with the retained flag set to true. The client can decide how it wants to process the retained messages.

Retained messages help newly-subscribed clients get a status update immediately after they subscribe to a topic. The retained message eliminates the wait for the publishing clients to send the next update.

In other words, a retained message on a topic is the last known good value. The retained message doesn’t have to be the last value, but it must be the last message with the retained flag set to true.

It is important to understand that a retained message has nothing to do with persistent sessions (a subject that we covered last week). Once a retained message is stored by the broker, there’s only one way to remove it. Keep reading to find out how.

Send a retained message

From the perspective of a developer, sending a retained message is quite simple and straight-forward. You just set the retained flag of a MQTT publish message to true. Typically, your client library provides an easy way to set this flag.

Delete a retained message

There is also a very simple way to delete the retained message of a topic: send a retained message with a zero-byte payload on the topic where you want to delete the previous retained message. The broker deletes the retained message and new subscribers no longer get a retained message for that topic. Frequently, it is not even necessary to delete, because each new retained message overwrites the previous one.

Why and when should you use Retained Messages?

A retained message makes sense when you want newly-connected subscribers to receive messages immediately (without waiting until a publishing client sends the next message). This is extremely helpful for status updates of components or devices on individual topics. For example, the status of device1 is on the topic myhome/devices/device1/status. When retained messages are used, new subscribers to the topic get the status (online/offline) of the device immediately after they subscribe. The same is true for clients that send data in intervals, temperature, GPS coordinates, and other data. Without retained messages, new subscribers are kept in the dark between publish intervals. Using retained messages helps provide the last good value to a connecting client immediately.


That’s the end of part eight in our MQTT Essentials series. We hope you enjoyed it. In the next post, we talk about a feature called Last Will and Testament. This feature makes it possible to send a last message when a client disconnects abruptly.

Have a great week and we hope to see you on the next MQTT Monday!

If you would like to get notified about each new post as soon as its available, use the subscription form to sign up for our newsletter. If you prefer RSS, you can subscribe to our RSS feed here.

MQTT 5-Essentials

About The HiveMQ Team

We love writing about MQTT, IoT protocols and architecture in general. Our experts are here to help, so reach out to us if we can help!
Contact us
HiveMQ 2.3.0 released
Persistent Session and Queuing Messages - MQTT Essentials: Part 7