Configuring Auto Subscribe
Last updated:2026-01-30 14:55:29
Auto Subscribe is an additional feature supported by MQTT beyond the standard protocol. It allows preset subscription relationships to be automatically established when a client connection is created, based on rules configured in the console, without requiring the client to initiate a subscription or send a SUBSCRIBE message. This feature applies to the following scenarios:
Unified management of IoT device subscription behavior
Simplify client-side code logic
Ensure specified devices automatically subscribe to key business topics (such as command delivery channels) without the need to actively initiate subscriptions.
Restrictions and Limitations
The current feature is in grayscale. If the console prompt shows the current cluster has not enabled this feature, please submit a ticket to contact us and submit a request.
A single cluster supports creating a maximum of 10 auto subscription rules.
Subscription Rule Description
Auto subscription rules are judged on the client when connecting. If the client is already online, after configuring the auto subscription rules for the client, the client will not immediately subscribe to the corresponding topic. In such cases, auto subscription rules will only take effect when the client connects next time.
Auto subscription rules will follow the latest configured rule if a configuration conflict occurs (such as the same username subscribing to the same Topic Filter with inconsistent subscription options). Rules will be overwritten in chronological order.
The number of subscriptions within auto subscription rules are also counted against the cluster and per-client ID subscription limits (see Product Constraints and Usage Quotas). Therefore, please monitor the quantities of auto subscription rules to prevent misuse.
When multiple subscription scenarios conflict with quota limits, rate limiting will be based on the priority: "non-Clean Session subscriptions (historic existing subscriptions) > auto subscription rules > newly-added manual subscriptions by clients". For example:
Case 1: Before creating an auto subscription rule, a client had 28 subscriptions. After the auto subscription rule is configured, 5 additional Topic Filter subscriptions were added. After the client disconnected and reconnected, it began subscribing to the new Topic Filters according to the auto subscription rules. When reaching the third Topic Filter, it exceeded the per-client limit of 30 subscriptions. The subscriptions for the 3rd to 5th Topic Filters within the auto subscription rule failed to take effect. Subscription failure events and reasons can be viewed on the client details page. For details, see Query Client Events.
Case 2: An online client currently has 20 subscriptions. After 10 Topic Filter subscriptions are added from an auto subscription rule, the total (30) remains within the limit, so the subscriptions succeed. Later, when the client launches a new business and adds one more Topic Filter subscription, the total exceeds the limit (31>30), causing the new subscription to fail. The subscription failure event and its reason can be viewed on the client details page. For details, see Query Client Events.
Case 3: A client has Clean Session = false and already has 30 subscriptions. Later, an auto subscription rule containing 10 Topic Filters is added. When the client reconnects before the session expiration period, it first restores historical subscriptions. Auto subscriptions matching the Topic Filters of historical subscriptions are directly overwritten. Then it proceeds to subscribe to the new Topic Filters within the auto subscription rule. However, all new Topic Filters exceed the quota limit, causing subscriptions for the exceeding portion to fail. Subscription failure events and reasons can be viewed on the client details page. For details, see Query Client Events.
Prerequisites
Ensure that clients applicable to the auto subscription rule have permissions to connect (CONNECT) to the cluster, subscribe using the specified username, and subscribe (SUBSCRIBE) to corresponding topics. Otherwise, the auto subscription will be denied by the permission policy. For details, see Configure Data Plane Authorization.
Operation Steps
Creating an Automatic Subscription Rule
1. Log in to the MQTT console.
2. Click Resource > Cluster in the left sidebar. After selecting a region, click the "ID" of the target cluster to enter the cluster basic information page.
3. Select the Auto Subscribe tab, click Create Rule to create an automatic subscription rule, and fill in the following fields as required:
Parameter Items | Required | Description | Example Value |
Rule Name | Yes | Enter the subscription rule name, which must comply with the naming rule: cannot be empty, 3-64 characters, supports Chinese, letters, numbers, "-", and "_". | device_cmd_sub |
Rule Description | No | Fill in the rule remark and description. | - |
Creation Method | - | Policy generator: visual configuration. JSON: Use JSON grammar to configure. The input box validates .json file format, suitable for scenarios with considerable configuration items. | - |
Username | Yes | Please enter a single username or expression. Wildcard and Policy variables are supported. For details, see Expression Description. Please ensure the current username has corresponding data plane permission. | * |
Client ID | Yes | Enter a single resource expression. Wildcard and Policy variables are supported. For details, see Expression Description. Please ensure the current client has corresponding data plane permission. | * |
Subscription Options | Yes | Add up to 20 subscription topics. Topic Filter: target topic filter for auto-subscription QoS:0/1/2. No Local: whether the client receives messages published by itself. Retain as Published: whether to keep the original Retain flag when forwarding retained messages. Retain Handling: whether to send retained messages when a subscription is established. | "topicFilter": "home/#", "qos": 0, "noLocal": 0, "retainAsPublished": 1, "retainHandling": 0 |
4. Click Submit to complete the rule creation.
5. After creating a rule, the default rule is in a "disabled" state. Click Enable in the operation bar, and the rule will take effect.
Managing Auto Subscribe Rule
1. Log in to the MQTT console.
2. Click Resource Management > Cluster Management in the left sidebar. After selecting a region, click the "ID" of the target cluster to enter the cluster basic information page.
3. Select the Auto Subscription Management tab, you can manage auto-subscription rules in the operation bar.
Operation | Description |
Editing an alarm policy | Click Edit in the Action column to edit an existing rule. |
Copying | Click Copy in the Action column to perform simple modifications on a rule and create similar rules. |
Delete | Only rules in the "Not Enabled" state support deletion. Therefore, to delete a rule, you must first disable it before proceeding with deletion. |
Was this page helpful?
You can also Contact Sales or Submit a Ticket for help.
Yes
No
Feedback