MQTT over WebSocket Client
Connect to an MQTT broker over WebSocket, subscribe and publish text or binary messages with MQTT 3.1.1 or 5.0.
Connect, Subscribe and Publish communicate directly with the selected broker.
Use an MQTT WebSocket listener
Supply a ws:// or wss:// broker endpoint with its WebSocket path. A TCP MQTT port such as 1883 is not a browser WebSocket endpoint. The page uses MQTT.js 5.16.1 and the MQTT protocol, not a raw WebSocket echo format. Example only fills an illustrative address and topic; it never connects or subscribes automatically.
Choose MQTT 3.1.1 or 5.0, then set the broker’s credentials and client ID. A blank ID with a clean session generates a fresh 23-character alphanumeric ID using browser cryptographic randomness. Persistent sessions require an explicit ID; another client using the same ID can displace this connection. Secure pages normally need WSS, and server Origin, TLS and browser WebSocket policies still apply. There is no server proxy or native TCP transport.
Subscribe, publish and inspect acknowledgements
A subscription filter accepts + for exactly one topic level and # as a final whole-level wildcard. Empty levels are valid. Shared filters use $share/group/filter and require broker support. A wildcard at the first level does not automatically select $SYS topics. Publish topics cannot contain wildcards.
Select a requested subscription QoS, then inspect the actual SUBACK grant. Publication QoS 0 completes after a socket write, QoS 1 after PUBACK and QoS 2 after PUBCOMP. These are protocol completion states, not proof that a subscribing application processed the message. Incoming records contain the topic, negotiated message QoS, retain and dup flags, exact hex bytes and UTF-8 text when decoding is valid.
Text input is encoded as UTF-8; hex accepts complete byte pairs separated by whitespace. Empty payloads are supported. Retain can replace the broker’s stored value; publishing an empty retained payload can remove that retained value. Unsubscribe removes a filter after the broker acknowledges it. It does not erase retained broker data.
Sessions and connection cleanup
Clean means Clean Session for 3.1.1 and Clean Start for 5.0. MQTT 5 session expiry is 0–86,400 seconds; it is disabled for 3.1.1. Session Present is recorded from CONNACK. This client keeps stores only in memory and does not restore in-flight QoS transactions after Clear, a new page or a new client instance; broker persistence alone cannot guarantee lossless session recovery.
Automatic reconnect, resubscribe and offline QoS-0 queuing are disabled. A new connection is explicit. Connection timeout covers the CONNACK handshake (1–30 seconds); operation timeout covers publish/subscribe/unsubscribe callbacks (1–30 seconds). An operation timeout stops the connection rather than leaving an ambiguous pending operation indefinitely. A broker may have acted before a timeout.
Disconnect requests MQTT DISCONNECT and gives pending work up to two seconds before forced cleanup. Changing connection fields or Clear stops the old client and ignores late callbacks; changing topics or payload keeps the connection. Leaving the page requests cleanup. No credentials, sessions or logs are saved in browser storage. Last Will configuration and advanced MQTT 5 properties are not exposed.
Limits and exporting
The client tracks at most 32 subscription filters and 20 pending operations. Message payloads are capped at 256 KiB. Client IDs are limited to 128 UTF-8 bytes; MQTT text fields reject controls, NUL, surrogate and noncharacter code points. Usernames and passwords must fit their protocol byte limits. Keepalive is 0–300 seconds; zero disables protocol keepalive.
The bounded log holds at most 1,000 records or 2 MiB of compact serialized event data and disconnects at the limit. The MQTT library and browser may receive packets before application-level payload checks run; MQTT 5 also advertises a 1 MiB maximum packet size. This is a manual debugging client, not a load tester.
Preview stops at 200,000 characters. Copy and Download report include the complete retained log. Connection records omit passwords and usernames, but broker errors, topics or payloads can contain private data. JavaScript does not bypass the broker’s authentication or authorization rules.
Questions & answers
Can I connect to mqtt:// or a WebSocket echo server?
No. Use the broker’s MQTT-over-WebSocket listener with the correct path, version and credentials.
Does QoS 2 mean a business action ran exactly once?
No. Its guarantee is scoped to MQTT protocol delivery between participating peers. Application processing, persistent recovery and downstream systems have their own behavior.
Why can a message still arrive just after Unsubscribe?
Messages already received or in flight can race with the acknowledgement. Unsubscribe changes the broker subscription; it does not undo already delivered work.
Other Languages
References
How we make sure
We check this tool with the automated test suites linked below. Example checks are shown in their original language.
- Verification method
- Check topics, QoS, protocol versions and binary payloads; integration cases exercise local-broker auth, retained messages and sessions.
- Comparison reference
- A Mosquitto WebSocket broker and fixed message/event assertions.
- Verification scope
- Real-broker cases require Mosquitto; mocked passes cannot substitute for missing interoperability runs.
Test source and cases (select a file to read it)
-
mqtt-graphql-tools.test.js
- MQTT strict URL, credentials, protocol, session and time option validation
- MQTT topic filters handle empty levels, shared groups, wildcards and forbidden text
These checks cover the listed examples and boundaries, not every possible input. Round trips and checks using the same library are not independent verification.