MQTT
Access existing users, channels and messages over MQTT 5 TCP or WebSocket, with explicit preview boundaries.
MQTT is an IM entry protocol for WuKongIM. It shares UIDs, device tokens, channels, membership permissions and messages with HTTP and WKProto SDKs. Your application still owns login, business authorization and payload formats.
Development preview
The MQTT listener is disabled by default and supports MQTT 5 TCP and an optional separate WebSocket listener. Complete Linux, fault and load qualification remains outstanding. Use a matching development candidate containing the MQTT implementation; do not assume current released packages or images support it.
Start here
Send your first message
Exchange messages between Alice and Bob using Node.js and pinned MQTT.js.
Authentication and topics
Prepare credentials, ClientIDs and canonical topics.
Message contract
Payloads, properties, idempotency and acknowledgement boundaries.
Persistent sessions and QoS
Recover subscriptions, handle duplicates and inspect Session Present.
Will messages
Abnormal disconnects, Will Delay, cancellation and authorization.
HTTP / SDK interoperability
Share channels and payloads; convert HTTP Base64 correctly.
Operations and troubleshooting
Cluster consistency, logical quotas and connection diagnosis.
Supported capabilities
| Capability | Current behavior |
|---|---|
| Version and transport | MQTT 5.0 over raw TCP or WebSocket; other versions unsupported; TLS terminates upstream |
| Browsers | MQTT.js can connect directly to a separate /mqtt listener; the mqtt subprotocol and binary messages are required |
| Publish QoS | 0 and 1; no QoS 2 publication |
| Subscription QoS | 0 and 1; a request for 2 may be granted 1; inspect SUBACK |
| Topics | Exact personal inbox and group-message topics; no arbitrary business topics |
| Retain | Unsupported; Retain Available is 0 in CONNACK |
| Wildcards and shared subscriptions | No +, # or $share/ |
| Topic Alias | Unsupported; Topic Alias Maximum is 0; send full topics |
| Authentication | CONNECT User Name / Password; no enhanced AUTH negotiation |
| Sessions | Clean Start, Session Expiry, Session Present; maximum offline lifetime 24 hours, configurable downward |
| Subscription options | No Local and Subscription Identifier supported; identifiers must be nonzero and not duplicated |
| Will | QoS 0/1 and Will Delay; no retain; current permissions checked at execution |
Inspect capabilities in CONNACK and each subscription's SUBACK. Client-library support does not establish server support.
Integration model
Your trusted backend prepares user tokens and group membership. Clients then connect and subscribe to exact topics. SUBSCRIBE establishes reception intent for a ClientID; it neither creates an account nor joins a group.
Successful PUBACK, SDK SENDACK and HTTP reason=1 acknowledge message commit. None proves recipient reception, reading or business completion. Every deployment retains cluster semantics. A single-node cluster also uses Slots and durable paths, with 256 hash slots by default.
The OASIS MQTT 5.0 specification defines the base protocol. This topic adds WuKongIM authentication, topic and IM mapping conventions.