MQTT Retained Messages for Instant State Sync - ApsaraMQ for MQTT

This topic describes the retained message feature of MQTT.

Feature introduction

A retained message is a message that a client publishes to a topic and flags for the server to retain.

New clients that subscribe to the topic immediately receive this retained message. They do not need to wait for a new message to be published.

Limits

This feature is available only for the Professional and Platinum Editions. To enable it, submit a ticket.
Only one retained message can exist for a single topic. A new retained message overwrites the previous one.
When subscribing with a wildcard character, the subscription can match a maximum of 100 parent and child topics.
For a Quality of Service (QoS) level of 1 or 2, the server retries sending a retained message a maximum of one time. When a client subscribes to a topic with a retained message, the server sends the message. If the server does not receive an acknowledgment before the request times out, it retries sending the message. If this retry is also not acknowledged, the server stops retrying for the current connection. The server will only retry when the client reconnects and subscribes.

Scenarios

Status updates: In Internet of Things (IoT) applications, a device can periodically publish its status, such as temperature and humidity, as a retained message. When a new client connects and subscribes, it immediately receives the latest device status.
System configuration: A system can publish a retained message that contains configuration information. New devices that join the network can directly retrieve the latest configuration.
Last known value: In scenarios such as stock trading or price quoting, the last price can be sent as a retained message. This ensures that all new subscribers can directly retrieve the last traded price.
Welcome messages: For example, when a new client subscribes to a chat room topic, it can immediately receive a welcome message for that room.

Message example

For example, a weather station device periodically publishes temperature data to the "weather/station1/temperature" topic. When it publishes the message, it sets the retain flag to make it a retained message.

PUBLISH
Topic: weather/station1/temperature
Payload: 24.5
QoS: 1
Retain: 1 // Instructs the broker to retain this message

Later, even if the device does not publish new temperature data, a new client can subscribe to "weather/station1/temperature" as follows:

SUBSCRIBE
Topic Filter: weather/station1/temperature
QoS: 1

The client will then immediately receive the last temperature data published by the weather station (the retained message):

PUBLISH
Topic: weather/station1/temperature
Payload: 24.5
QoS: 1
Retain: 1 // The client is notified that this is a retained message

Using retained messages, new clients can immediately retrieve the temperature status without waiting for the next update. This increases the system's responsiveness and provides immediate context for new participants.