MQTT over Websockets with HiveMQ

One of the big new features of the HiveMQ 1.4 release is definitely the native support for MQTT over Websockets. Every modern browser on any device is now a potential full-fledged MQTT client. With real publish/subscribe in the browser, web apps can take full advantage of highly scalable messaging with a very low bandwidth footprint.

Why websockets

Websockets are around for a long time now. There were many competing websocket implementations and almost every browser had its own implementation specific idiosyncrasies. Nowadays most relevant browsers support websockets. Websockets have very little overhead in terms of bandwidth and latency compared to classic HTTP requests which are needed when using (long) polling. This philosophy of having as little overhead as possible fits very well to MQTT.

With MQTT over websockets every browser can be a MQTT device. Due to the publish/subscribe pattern of MQTT, you get a real time push to your browser when an event – literally anywhere in the world – occurs, as long as you subscribe to the correct topic. With MQTT you get the following features on top of standard websocket pushes:

  • Quality of Service semantics: When using QoS 1/2, you get the assurance that your message arrived on the client or broker at least once/exactly once.
  • Queuing: When using QoS 1 or 2 and a persistent session, the broker will queue all messages your client misses from its subscriptions when it’s not connected. On reconnect, all messages are delivered instantly to your client.
  • Retained messages: Messages which are retained on the server are delivered when your client subscribes to one of these topics instantly.
  • Last Will and Testament: If your client doesn’t disconnect gracefully, it’s possible to publish a message to a topic to notify everyone who is interested, that your client died.
  • If your client connects to the broker with a persistent session, you don’t have to resubscribe to all the topics your client is interested to, as all previous subscriptions are stored on the server.

How do websockets and MQTT fit together?

Messages over websockets are sent in frames. These frames have only 2 byte overhead. The whole MQTT message (with all its headers and payload) is now sent with the websocket frame.


MQTT Messages in Websocket Frames

HiveMQ expects that every MQTT message is sent in exactly one websocket frame. Common Javascript MQTT libraries like Paho.js implement this behaviour.

Native Websockets

HiveMQ implements all websocket standards (including RFC6555, all hixie and all hybi drafts) natively. That means, that you don’t need a dedicated webserver in front of a HiveMQ MQTT broker instance to forward the websocket connection. HiveMQ handles the HTTP websocket upgrade and the actual websockets transparently. The broker treats a MQTT client connection over websockets as equal to connections over “plain TCP”.

Other MQTT brokers with the need for an additional web server

The following shows any MQTT broker without websockets support and how MQTT over websockets could be achieved:

Websockets with a MQTT broker and a Webserver

Websockets with a MQTT broker and a Webserver

As you can see an additional webserver is needed. Unfortunately many webservers (like Apache or lighthttpd) need specific modules or source patches if you want to forward the websocket connection to your MQTT broker. And of course you have to configure the web server properly.

HiveMQ with native websockets

In contrast, the following shows how MQTT over websockets are done with HiveMQ:

Websockets with HiveMQ - No additional webserver needed

Websockets with HiveMQ – No additional webserver needed

As you can see, a web application which utilizes websockets is a first class MQTT client for HiveMQ. No additional web servers needed, no fiddling around with obscure config files. It just works out of the box.


To enable websockets, just set the following properties in the file:

For a full list of configuration options, please refer to the official documentation.

Secure Websockets

Secure Websockets are a great way to enable security on the transport layer. HiveMQ offers secure websockets out of the box. It’s even possible to use secure websockets and standard websockets simultaneously.

To enable secure websockets, add a valid certificate to HiveMQs keystore and set the following properties in the file:

Client libraries

At the moment we strongly recommend Eclipse Paho.js as the MQTT Javascript client library. It works perfectly, has a very intuitive API and is documented very well. You should absolutely try it.


MQTT over Websockets has many advantages and enables you to write a new generation of web applications. With HiveMQ it’s dead easy to use websockets, they just work out of the box without any complicated configuration. You don’t need any additional software, you just have to enable websockets in the HiveMQ config.

We are curious what cool app you want to build with MQTT over Websockets. Drop us a line or write a comment!