MQTT 5.0 user properties let you attach custom key-value metadata to control packets, enabling richer device-to-application communication without modifying the message payload.
How user properties work
User properties are custom key-value pairs attached to MQTT 5.0 control packets. They work like HTTP headers: you define the keys and values as UTF-8 strings, and the broker passes them along with the packet.
User properties are a foundational part of MQTT 5.0. Several built-in protocol features—session expiry, message expiry, and the request-response pattern—are implemented using properties. Custom user properties extend that mechanism to your own use cases.
You can attach user properties to all MQTT 5.0 control packets except heartbeat packets. The following PUBLISH packet includes two user properties:
Topic: "sys/${productkey}/${devicename}/update"
Payload: "hello world!"
UserProperty: "key1_timestamp:value1_12345"
UserProperty: "key2_msgid:value2_123"Limits
You can specify up to 20 user properties.
IoT Platform processes user properties only for
Connect/Publishpackets. User properties on other packet types are ignored.
Use cases
Message content format
Use user properties to describe what a payload contains. A single topic can then carry payloads of different types or from different device batches, and subscribers can route or parse messages based on user property values instead of inspecting the payload itself.
Message segmentation
MQTT is designed for small packets. MQTT 5.0 lets devices negotiate the maximum packet size with IoT Platform. When a message exceeds that limit, use user properties to split it into sub-messages. The business server reads the user properties on each sub-message to identify and reassemble the original message. The following diagram shows Device A splitting a single message into Message A and Message B. For more information, see Server-side subscription.
Message forwarding
Use a user property to tag a message with its type and intended destination. The rules engine reads that tag and forwards the message accordingly. The following diagram shows how to set the UserProperty parameter so that Device A's messages are routed to different destinations based on message type. For more information, see Overview.
