You can retrieve the current online status of the Message Queue for MQTT client (referred to here as the client) by using the synchronous query method or asynchronous online/offline notification method.

Message Queue for MQTT must be used with backend MQ services (such as Message Queue for Apache RocketMQ) and work with applications that are deployed on cloud servers (hereinafter referred to as service applications) to complete service processes.

The main scenarios for retrieving the online status of the client are as follows:

  • The subsequent operation logic needs to be determined based on whether the client is online or not during the main service process.
  • The online status of a specific client needs to be determined during the O&M process.
  • Service applications need to trigger some predefined actions when a client goes online or offline.

Basic principle

The Message Queue for MQTT broker supports the following methods for retrieving the online status of the client:
  • Call the synchronous query interface

    This method is relatively simple and applicable to only query the status of a single client. A new set of SDK is to be provided for you in the future to query the real-time status of a specific client.

    Note The HTTP/HTTPS API through an open endpoint to query the online status of a specific client is unavailable.
  • Asynchronous online/offline notification

    This method uses notification messages. When a client goes online or offline, the MQTT broker pushes an online or offline message to backend MQ. Service applications are generally deployed on Alibaba Cloud ECS instances. Service applications can subscribe to this message from backend MQ to retrieve the online/offline events of all clients.

    This method perceives the client status asynchronously and detects the online and offline events rather than the online status of the client. Therefore, cloud-based applications need to analyze the client status based on the timeline of a series of events.

The differences between both methods are as follows:
  • The synchronous query method queries the real-time status of a client. Theoretically, it is more precise than the asynchronous notification method, but it only supports the status query of a single client at one time.
  • Asynchronous online/offline notification messages are based on message decoupling, so status determination is more complex and more likely to be incorrect. However, this method can analyze the running status traces of multiple clients based on events.

Asynchronous online/offline notification

As described in Basic principle, if the asynchronous online/offline notification method is used, online and offline events are mapped to backend MQ.

The following uses MQ as backend MQ to demonstrate this.


  1. Create a topic that corresponds to online and offline events.

    In the Message Queue for MQTT console, create a topic for the device with the target group ID. For information about how to create a topic, see Create a topic and group ID in MQTT quick start.

    For example, if the target client type corresponds to the group ID GID_XXX, then the client ID and topic for this client type are GID_XXX@@@YYYYY and GID_XXX_MQTT, respectively.


    • GID_XXX indicates the group ID created in the Message Queue for MQTT console.
    • YYYYY indicates the device ID and is concatenated with the group ID to form the client ID in the format of <GroupID>@@@<DeviceID>.
    • _MQTT indicates the fixed suffix that is required in the name of the topic for this type of event notifications.

    For more information, see Terms.

  2. Service applications subscribe to this type of notifications.

    Use the topic created in step 1 to receive the online and offline events of the target client. For information about how to receive messages from MQ, see Subscribe to messages.

    The event type is included in an MQ message tag, indicating whether it is an online or offline event. The data format is as follows:

    RocketMQ Tag: connect/disconnect/tcpclean


    • A connect event indicates an online event of the client.
    • A disconnect event indicates that the client proactively disconnects from the MQTT broker. According to MQTT, the client sends a disconnect packet before proactively releasing the TCP connection. The MQTT broker triggers the disconnect message after receiving the disconnect packet. If a client SDK does not send the disconnect packet, the MQTT broker cannot receive the disconnect message.
    • A tcpclean event indicates that the current TCP connection is disconnected. If the current TCP connection is disconnected, a tcpclean event is triggered regardless of whether the client has explicitly sent a disconnect packet.

    A tcpclean message indicates that the network-layer connection of the client is disconnected. A disconnect message only indicates that the client proactively sends a disconnect packet. Some clients may fail to send a disconnect message due to unexpected exit. This is subject to the implementation on the clients. Therefore, determine whether a client is offline based on the tcpclean event.

    Data content is of the JSON type and related keys are as follows:

    • clientId indicates a specific device.
    • time indicates the event time.
    • eventType indicates the event type, which is used by clients to differentiate events.
    • channelId uniquely identifies each TCP connection.
    • clientIp indicates the Internet egress IP address used by a client.


    clientId: GID_XXX@@@YYYYY
    clientIp: 192.168.X.X:133XX     

    To determine whether a client is online, check the last received message while considering the context of online/offline notification messages.

    The determination rules are as follows:

    • The sequence of online and offline events generated by clients with the same client ID is determined by time. That is, a more recent event has a greater timestamp.
    • Clients with the same clientId may be transiently disconnected multiple times. Therefore, when an offline notification message is received, you need to check whether the message is related to the current TCP connection based on the channelId field. In short, an offline notification message can only overwrite an offline notification message with the same channelId. If channelIds of offline notification messages are different, the offline notification messages cannot be overwritten even if the value of time is more recent.