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.


For HiveMQ 2.x

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

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

For HiveMQ 3.x

Edit the config.xml file:

You can find the complete documentation here.

Secure Websockets

For HiveMQ 2.x

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:

For HiveMQ 3.x

Edit the config.xml file:

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

Client libraries

We can recommend the following Libraries:


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!


  1. samir says:


    I’ve tried the websocket client on an android device with chrome. unfortunately it does not work. There is a connection error (unknow). However the browser is able to perform basic websocket communication.
    I would appreciate any feedback on this issue.

    Thank you

    1. Hi samir,

      there should be no problem using MQTT over Websockets with the Android version of Chrome.
      Can you please check, which version of Chrome do you use and compare it with the following web site [1].
      Also please double check that port 8000 is open in your network.

      Hope that helps,


  2. Shashank says:

    Can I use MQTT with WebSockets in android to connect to broker and publish messages the device is behind a proxy network?

    1. Hi Shashank,

      this depends a lot on the type of proxy. It should work if your library supports MQTT over websockets and your proxy allows websocket traffic.

      Dominik from the HiveMQ team

  3. Shreya says:

    In the conf folder, there’s no file called so I’m not able to run it. (I have hivemq-3.0.3) Please help!

    1. Hi Shreya,

      HiveMQ 3 changed the configuration format. You can learn how to upgrade the file from 2.x to 3.x here:

      If you’re starting with a fresh HiveMQ 3.x installation, you can find an example here:

      Hope this helps,
      Dominik from the HiveMQ Team

  4. sahil says:

    I am using the websocket client : for testing out hivemq.

    It seemed to be working fine for sometime but now no matter what I do I am not able to connect and it gives connection timed out.

    What could be the probable causes?


    1. Hi Sahil,

      this could have multiple causes, e.g. firewall issues or the broker you’re connecting to is not available.

      Hope this helps,

  5. Vishnu says:


    We have an “API management and Connect gateway” application from where we can publish or subscribe Rest API using HTTP protocols we have used technologies as vertex and nginx etc. Now We need to support MQTT protocols for the application. Where we can create a an API that will talk to broker and there is raspberry pi client who is publishing the data on some topic to broker and another web / java client will subscribe the same topic and every thing has to be done through gateway and API.

    Please guide us if we are on right direction.



  6. Prathamesh says:

    Hey. How can I deploy HiveMQ on a public IP ? Is the procedure same ?
    I tried deploying it on my public IP. The broker is getting started but the client is not getting connected with it.

    1. Hi Prathamesh,

      make sure you bind the HiveMQ listener to the corresponding NIC’s IP address. Please take a look at our documentation how to do this:

      Also make sure that no firewall policies (e.g. iptables) prohibit the access to your port. If you’re on cloud providers, make sure the Security Group (or whatever your cloud providers concept for that is) allow the access to the machine.

      Hope this helps,

    2. Prathamesh says:

      Hey Dominik,
      Can’t I bind it to “” address ?

    3. Hello Prathamesh,

      binding to should be OK. If you bind to that, you essentially bind to all interfaces.


  7. Harsh Pandey says:

    I am using HiveMq-3.2.3 on my raspberry pi.I have successfully tested mqtt through HIve but I am facing problem when trying the same for MQTT over websockets through HIve. I am getting any information on importing paho.js library. Can anyone tell me a detailed procedure or can refer me to an article for implementing mqtt over websockets on raspberry pi.I have already changed the config.xml from mqtt configuration to as described above for HiveMq-3.2.3.

  8. Nouman Ali says:

    I’ve implemented HiveMQ on Windows 10 and using it as a broker to communicate between multiple NodeMCU devices and it’s working all good in a single network.
    The problem I’m facing is when I’ve multiple networks (subnets) then the NodeMCU devices are unable to communicate with the broker. Is there any way through they can communicate with the broker.

    The problem occurs when my broker is on another subnet and my NodeMCU devices are on another subnet.
    Any help will be much appreciated. Thanks.

    1. Hi,

      your devices must be able to open a TCP connection to your broker.
      With multiple subnets you could for example use NAT to make your broker accessible from the other subnet.

  9. Keshore Suryanarayanan says:


    I am using Arduino IDE to implement ESP8266 as a client for MQTT over Websockets, with HiveMQ broker installed on my Windows 10 PC. I have tested MQTT based communication with the same broker and client using PubSubClient library, now how different is the procedure to test MQTT over Websockets for the same?


    1. Hallo Keshore,

      Nice to see you are taking an interest in MQTT and HiveMQ.
      This blog post covers all the needed configuration on HiveMQ’s end.
      I am not certain if and how the PubSubClient Library supports MQTT over Websockets.
      Changing your broker connection from tcp://broker-ip:tcp-port(1883 by default) to ws://broker-ip:ws-port(8000 by default) should be how you address the websocket listener on the HiveMQ.
      For details on the PubSubClient Library please refer to the PubSubClient homepage

      Kind regards,
      Florian from the HiveMQ Team.

Leave a Reply

Your email address will not be published. Required fields are marked *