MQTT

Connect to an MQTT broker, subscribe to topics and publish messages, with a live log of everything that arrives.

What MQTT is

MQTT is a lightweight messaging protocol, common in sensors and home automation. Devices do not talk to each other directly. They all connect to a server called a broker.

• A client publishes a message to a topic, a name such as home/livingroom/temperature.
• A client subscribes to topics it cares about. The broker passes on every message published to them.

ApiWorkbench acts as one such client. It speaks MQTT 3.1.1.

Make your first connection

This example uses test.mosquitto.org, a public test broker. Everyone can read what is published there, so do not send anything private.

1. In the tab bar, select the small arrow next to + and choose MQTT.

   A tab named New MQTT opens with mqtt://localhost:1883 in the URL field.

2. Change the URL to mqtt://test.mosquitto.org:1883.

3. Open the Subscribe tab and select Add subscription.

4. In Topic filter, type a topic of your own, for example apiworkbench-demo/hello.

5. Select Connect, or press Enter in the URL field.

   The status changes to Connected, and the subscription shows active.

6. Open the Publish tab. Type the same topic in Topic and hi in Payload.

7. Select Publish.

   The log lists the message you sent and the copy the broker delivered back to you, with its topic, QoS and retain flag.

Good to know

To test without the internet, run a broker on your own computer, such as Mosquitto, and connect to mqtt://localhost:1883.

Broker URL

The URL starts with	Connection	Default port
mqtt:// or tcp://	Plain TCP	1883
mqtts://, ssl:// or tls://	TLS (encrypted)	8883
ws://	MQTT inside a WebSocket	80
wss://	MQTT inside an encrypted WebSocket	443

A bare host:port is read as mqtt://. For WebSocket brokers, the path after the host is kept, for example wss://broker.example.com/mqtt.

Connection

The Connection tab holds what is sent to the broker when connecting.

Setting	What it does	Default
Client ID	The name this client gives the broker. Two clients with the same id push each other off, so keep it unique. Empty makes up a random id for every connection. The button next to the field (Generate client ID) fills in a new random id.	Empty
Username	The user name the broker checks. Leave empty for brokers that allow anonymous clients.	Empty
Password	The password for that user.	Empty
Keep-alive (seconds)	How often the client pings an idle connection. 0 turns it off.	60
Clean session	On: the broker forgets this client's earlier subscriptions and queued messages. Off asks it to keep them between connections, which needs a fixed client id.	On
Reconnect automatically	Reconnect and subscribe again when the connection drops. Disconnect stops it.	Off

WARNING

The password is saved with the request as plain text. Put real secrets in a variable such as {{mqttPassword}} instead. See Variables.

Subscribe

Each row on the Subscribe tab is a topic filter with a QoS level and a switch.

• + stands for one level: sensors/+/temp matches sensors/kitchen/temp.
• # stands for everything below: home/# matches every topic that starts with home/.

Switched-on rows are subscribed when you connect. While connected, the switch subscribes and unsubscribes right away. Each row shows whether it is active and how many messages it has received. If you edit a topic while connected, select Subscribe on the row to subscribe to the new topic.

Publish

Field	What it does
Topic	The topic to publish to. Wildcards (+ and #) are not allowed here.
Payload	The message body. Choose Text, JSON or Binary (base64).
QoS	The delivery guarantee (see below).
Retain	The broker stores this message and hands it to every client that subscribes later, until it is replaced. Publish an empty payload with Retain to clear it.

Variables are filled in for the topic and the payload.

QoS levels

QoS	Meaning
0 · at most once	Sent once and not checked.
1 · at least once	Makes sure it arrives, possibly twice.
2 · exactly once	Makes sure it arrives exactly once, with more messages exchanged.

Last will

A last will is a message the broker publishes for you if this client disappears without disconnecting properly. Others can use it to see that you went offline.

On the Last will tab, turn on Send a last will, then fill in Will topic, Will payload, Will QoS and, if you want new subscribers to see it too, Retain will. The will is registered when you connect.

Headers and TLS

The Headers tab adds HTTP headers to the upgrade request. They are used only for ws:// and wss:// brokers.

TLS connections follow the app's Verify TLS certificates setting and trust the extra CA certificate, if you set one. See Proxy and certificates.

The message log

The lower pane lists each message with its topic, QoS and retain flag, and shows the client id in use. It works like the WebSocket log: search, filter, copy and clear. See Read the message log.

Next steps

• WebSocket
• Server-Sent Events
• Troubleshooting