Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/hivemq/hivemq-community-edition/llms.txt

Use this file to discover all available pages before exploring further.

​
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