Skip to main content

​
Overview

MQTT over WebSocket allows web browsers and applications to connect to HiveMQ CE using the WebSocket protocol. The default port is 8000.

​
Configuration

​
Basic WebSocket Listener

config.xml
<hivemq>
  <listeners>
    <websocket-listener>
      <port>8000</port>
      <bind-address>0.0.0.0</bind-address>
      <path>/mqtt</path>
      <name>websocket-listener</name>
    </websocket-listener>
  </listeners>
</hivemq>

​
Configuration Options

OptionDescriptionDefault
portWebSocket port8000
bind-addressNetwork interface0.0.0.0
pathWebSocket endpoint path/mqtt
subprotocolsSupported MQTT subprotocolsmqtt, mqttv3.1, mqttv3.1.1, mqttv5
allow-extensionsEnable WebSocket extensionsfalse

​
Full Configuration Example

<websocket-listener>
  <port>8000</port>
  <bind-address>0.0.0.0</bind-address>
  <path>/mqtt</path>
  <name>ws-listener</name>
  <subprotocols>
    <subprotocol>mqtt</subprotocol>
    <subprotocol>mqttv5</subprotocol>
  </subprotocols>
  <allow-extensions>true</allow-extensions>
</websocket-listener>

​
Browser Client Example

<!DOCTYPE html>
<html>
<head>
  <title>MQTT WebSocket Example</title>
  <script src="https://unpkg.com/mqtt/dist/mqtt.min.js"></script>
</head>
<body>
  <h1>MQTT WebSocket Client</h1>
  <div id="status">Disconnected</div>
  <div id="messages"></div>
  
  <script>
    // Connect to HiveMQ CE via WebSocket
    const client = mqtt.connect('ws://localhost:8000/mqtt', {
      clientId: 'web_' + Math.random().toString(16).substr(2, 8),
      keepalive: 60,
      clean: true
    });
    
    client.on('connect', () => {
      document.getElementById('status').innerHTML = 'Connected';
      console.log('Connected to MQTT broker');
      
      // Subscribe to topic
      client.subscribe('web/messages', { qos: 1 });
      
      // Publish message
      client.publish('web/status', 'Browser online', { qos: 1 });
    });
    
    client.on('message', (topic, message) => {
      const msg = message.toString();
      console.log(`Received: ${topic} = ${msg}`);
      
      const div = document.getElementById('messages');
      div.innerHTML += `<p>${topic}: ${msg}</p>`;
    });
    
    client.on('error', (error) => {
      console.error('Connection error:', error);
      document.getElementById('status').innerHTML = 'Error: ' + error;
    });
  </script>
</body>
</html>

​
Node.js WebSocket Client

const mqtt = require('mqtt');

const client = mqtt.connect('ws://localhost:8000/mqtt', {
  clientId: 'nodejs_websocket_client',
  keepalive: 60,
  clean: true,
  reconnectPeriod: 1000
});

client.on('connect', () => {
  console.log('Connected via WebSocket');
  client.subscribe('test/topic', { qos: 1 });
  client.publish('test/topic', 'Hello from WebSocket', { qos: 1 });
});

client.on('message', (topic, message) => {
  console.log(`${topic}: ${message.toString()}`);
});

​
MQTT 5 over WebSocket

const mqtt = require('mqtt');

const client = mqtt.connect('ws://localhost:8000/mqtt', {
  protocolVersion: 5,
  clientId: 'mqtt5_websocket',
  properties: {
    sessionExpiryInterval: 3600,
    receiveMaximum: 100
  }
});

client.on('connect', (connack) => {
  console.log('Connected with MQTT 5');
  console.log('Server properties:', connack.properties);
});

​
WebSocket Subprotocols

HiveMQ CE supports standard MQTT subprotocols:
  • mqtt - Generic MQTT
  • mqttv3.1 - MQTT 3.1
  • mqttv3.1.1 - MQTT 3.1.1
  • mqttv5 - MQTT 5.0
// Specify subprotocol
const client = mqtt.connect('ws://localhost:8000/mqtt', {
  protocolId: 'MQTT',
  protocolVersion: 5,
  wsOptions: {
    protocol: 'mqttv5'
  }
});

​
Docker Configuration

# Expose WebSocket port
docker run -d --name hivemq-ce \
  -p 1883:1883 \
  -p 8000:8000 \
  hivemq/hivemq-ce

​
Firewall Configuration

​
Linux (iptables)

sudo iptables -A INPUT -p tcp --dport 8000 -j ACCEPT
sudo iptables-save

​
Linux (firewalld)

sudo firewall-cmd --permanent --add-port=8000/tcp
sudo firewall-cmd --reload

​
CORS Configuration

HiveMQ CE WebSocket listener automatically handles CORS headers for browser compatibility. No additional configuration is required.

​
Use Cases

Web Dashboards

Real-time data visualization in browsers

Progressive Web Apps

Push notifications and real-time updates

Chat Applications

Browser-based messaging systems

IoT Monitoring

Web-based device management interfaces

​
Security Considerations

WebSocket connections over HTTP (ws://) are unencrypted. Use Secure WebSocket (wss://) for production.

​
When to Use WebSocket

  • ✅ Browser-based applications
  • ✅ Web dashboards
  • ✅ Progressive Web Apps (PWA)
  • ✅ Development with HTTP
  • ❌ Production without TLS
  • ❌ Public networks (use WSS instead)

​
Troubleshooting

  • Verify WebSocket listener is configured and port 8000 is open
  • Check firewall rules
  • Ensure correct path (/mqtt)
  • HiveMQ CE handles CORS automatically
  • Check browser console for specific errors
  • Verify WebSocket URL is correct
  • Ensure client and server support same MQTT version
  • Check configured subprotocols in config.xml

​
Next Steps

Secure WebSocket

Add TLS encryption to WebSocket

TCP Transport

Standard MQTT over TCP

Connecting Clients

More client examples

Configuration

Advanced listener configuration

Build docs developers (and LLMs) love

Get started for freeTalk to us