Publish messages

The Publish messages page publishes an MQTT message from the management console, on behalf of the broker itself: no MQTT connection or client credentials are involved. It is a form over the REST publish API, and the broker handles the message exactly as that page describes.

Open it from Publish messages in the left-hand menu. The page has three parts: the Published messages table at the top, the Request preview panel beside it, and the publish form below them.

The form opens pre-filled with a sample topic, sensors/temperature, and a sample JSON payload.

1. Enter the Topic — a topic name, not a filter: wildcards (+, #) and a leading $ are rejected. A warning icon in the field names the problem while the topic is missing or invalid.
2. Pick the QoS: 0 - At most once, 1 - At least once (the default), or 2 - Exactly once.
3. Pick the Encoding, which decides how the payload you type is turned into message bytes:
   • JSON (default) — the editor must hold valid JSON; the broker publishes its compact text.
   • Text — the payload is published as UTF-8 text.
   • Base64 — the payload holds raw bytes encoded as a Base64 string (A-Z, a-z, 0-9, +, /, optional = padding, no line breaks). Use it for binary payloads.
4. Switch Retain on to store the message as the retained message for the topic. With Text or Base64 encoding, an empty payload with Retain on clears the retained message instead — a JSON payload can never be empty.
5. Optionally click Properties to set the MQTT 5 properties. The badge on the button shows how many properties are set.
6. Type the payload in the editor and click Publish (the send icon). The button stays disabled while a publish is in flight, when the topic is missing or invalid, or when the payload is not valid JSON or Base64 for the selected encoding.

The Properties dialog sets the MQTT 5 PUBLISH properties sent with the message:

• Payload Format Indicator — when on, marks the payload as UTF-8 character data; when off, the property is not sent.
• Content Type — MIME type of the payload.
• Message Expiry Interval — how long the message stays valid, entered in seconds, minutes, or hours and sent to the broker in seconds. The MQTT maximum is 4294967295 seconds; a value above the limit for the selected unit is flagged with a warning icon and blocks Save.
• Response Topic — topic for a response in the request/response pattern; it has to be a valid topic name.
• Correlation Data — binary correlation data, entered as a Base64 string. A value that is not valid Base64 is flagged with a warning icon and blocks Save.
• User Properties — key-value pairs. A pair with an empty key or value is dropped.

Click Save to apply the properties to the next publish, Reset to clear them all, or Cancel to keep the previous values.

On this page, two properties are pre-set, so every publish carries a properties block until you change it: Content Type application/json and Message Expiry Interval 60 minutes. To publish without any properties, click Reset and then Save. The Publish message dialog starts with no properties.

How each property reaches subscribers — including the fact that MQTT 3.1.1 clients receive the payload without them — is described under MQTT 5 properties on the REST publish API page.

Every publish produces a result: a new row in Published messages on this page, or a panel under the form when publishing from the Publish message dialog. It shows a title, the HTTP status of the call, the PUBACK reason code when the broker returned one, and details — for a rejected request, the broker’s own message. A 503 is the exception: its details are the console’s own warning that the message may still have been published, not the broker’s answer. The statuses are those of the REST publish API; what each one means is described under Response codes on its page.

The table at the top of the page lists the messages published from the console during the current browser session, newest first — from this page and from the Publish message dialog on other pages alike. Messages published through the REST API directly are not listed. The list is kept in memory only and holds the newest 1000 messages; older ones drop off. It is emptied when the page is reloaded or when you click Clear messages.

Each row shows the Time, Topic, QoS, Retain flag, Encoding, Payload, Status, and HTTP status. The status is a label colored by outcome — Published, No subscribers, or Failed; hover over it to read the result title, HTTP status, reason code, and details. The HTTP status column holds the numeric status of the call. The table is paged.

Three row actions are available. Load into composer puts the message back into the form — its topic, QoS, Retain flag, encoding, payload, and the MQTT 5 properties it was sent with, replacing the properties currently set — so you can publish it again or edit it first. Payload opens the full payload, and Properties, shown only for messages that were sent with properties, opens them.

Messages published this way are stamped with the client ID tbmq_rest_api — see Publisher client ID. To trace every publish made through the REST API beyond the current session, including calls made outside the console, enable the audit log for REST publishes.

The Request preview panel shows the JSON body the form will send, updated as you edit the form or its properties — the same body the REST publish API documents. The copy icon in the panel copies that body alone.

Copy as cURL copies a ready-to-run shell snippet: an export TBMQ_JWT='…' line holding your current session token, followed by the curl -X POST call to /api/mqtt/publish with that body. It is a quick way to move a message you have tested here into a script.

Administrators can also open a Publish message dialog — the same form, with the result shown under it and no properties pre-set — from the pages where a topic is already at hand:

• Subscriptions page — the Publish to this topic row action pre-fills the topic and QoS of the subscription.
• Sessions page — in the session details, every row of the Subscriptions tab has a Publish to this topic icon that does the same for that session’s subscription.
• Retained messages page — the Publish message button in the top right corner opens the dialog with Retain already on. The Publish to this topic row action additionally pre-fills the topic and QoS of an existing retained message, so you can replace it — or clear it, with an empty Text or Base64 payload. The table refreshes when you close the dialog after a publish the broker accepted.

A subscription filter is not a topic name, so the pre-filled topic is derived from it: every + segment is replaced with a random alphanumeric segment, a trailing # is dropped, and so is the $share/<group>/ prefix of a shared subscription. sensors/+/temperature pre-fills sensors/<random>/temperature, $share/g1/sensors/# pre-fills sensors, and # pre-fills nothing. The pre-filled topic matches the filter, so it can be published as is; edit the random segments to target a specific topic. An info icon in the Topic field reminds you of the replacement until you edit the topic.