All Products
Document Center

IoT Platform:Configure MNS server-side subscriptions

Last Updated:May 11, 2023

IoT Platform allows you to send device messages to Message Service (MNS). Cloud applications can obtain the device messages by listening to MNS queues. This topic describes how to configure an MNS server-side subscription.


If you use a RAM user, the RAM user must have the AliyunIOTAccessingMNSRole permission.


  1. In the IoT Platform console, configure an MNS server-side subscription for a product. This way, IoT Platform automatically forwards messages to MNS.

    1. Log on to the IoT Platform console.

    2. On the Overview page, select an environment, find the instance that you want to manage, and click the instance ID or instance name.


      This step is required only if Enterprise Edition instances are available. If the Enterprise Edition instances are unavailable in the region that you selected, skip this step. For information about supported regions and instances, see Overview.

    3. In the left-side navigation pane, choose Message Forwarding > Server-side Subscription.

    4. On the Subscriptions tab of the Server-side Subscription page, click Create Subscription.

    5. In the Create Subscription dialog box, configure the parameters and click OK. The following table describes the parameters.




      Select the product to which the devices belong. The messages submitted by the devices are pushed to consumers.

      Subscription Type

      Select MNS.

      Message Type

      Select the types of messages. You can subscribe to the following types of device messages:


      If you use Message Queuing Telemetry Transport MQTT or JT/T 808 gateway products and devices, IoT Platform pushes only Device Upstream Notification, Device Status Change Notification, and Device Changes Throughout Lifecycle messages to the products and devices.

      • Device Upstream Notification: the messages in the topics whose Allowed Operations parameter is set to Publish.

        The messages include custom data and Thing Specification Language (TSL) data that is submitted by devices. The upstream TSL data includes property data, event data, responses to property setting requests, and responses to service calls. The TSL data that is pushed to user servers is processed by IoT Platform. For more information, see Data formats.

        For example, the following topic categories are defined for a product:

        • /${productKey}/${deviceName}/user/get. The Allowed Operations parameter of this topic category is set to Subscribe.

        • /${productKey}/${deviceName}/user/update. The Allowed Operations parameter of this topic category is set to Publish.

        • /${productKey}/${deviceName}/thing/event/property/post The Allowed Operations parameter of this topic category is set to Publish.

        The server-side subscription feature pushes the messages of the following topic categories: /${productKey}/${deviceName}/user/update and /${productKey}/${deviceName}/thing/event/property/post.

      • Device Status Change Notification: the notifications that are sent by devices when the devices go online or offline.

      • Gateway's sub-devices discovery report: the sub-device data that is submitted by gateways when the gateways detect new sub-devices. The gateways must have applications that can be used to detect sub-devices. This message type is specific to gateways.

      • Device Topological Relation Changes: the notifications that are sent by gateways when topological relationships between sub-devices and the gateways are created or deleted. This message type is specific to gateways.

      • Device Changes Throughout Lifecycle: the notifications that are sent by devices when the devices are created, deleted, enabled, or disabled.

      • TSL Historical Data Reporting: the historical properties and events that are submitted by devices.

      • OTA Update Status Notification: the notifications that devices send during update package verification and batch update. A notification is pushed regardless of whether a device update is successful or fails.

    6. In the dialog box that appears, click OK.

      IoT Platform automatically creates an MNS message queue in the aliyun-iot-${productKey} format. If you want to configure a queue listener, you must specify the message queue.

      You are charged for MNS resources. For more information about the billing methods of MNS, see MNS billing.


      If you delete the MNS server-side subscription, the related MNS queue is automatically deleted.

  2. Configure an MNS client and listen to the MNS queue to receive device messages.

    In this example, MNS SDK for Java is used to listen to the MNS queue.

    For information about how to download the SDK, see the MNS documentation.

    1. To install MNS SDK for Java, add the following dependencies to the pom.xml file:

    2. Configure the following parameters when you configure the SDK:

      CloudAccount account = new CloudAccount( $AccessKeyId, $AccessKeySecret, $AccountEndpoint);
      • Replace $AccessKeyId and $AccessKeySecret with the AccessKey ID and AccessKey secret of your Alibaba Cloud account. The parameters are required when you call API operations. To create or view an AccessKey pair, log on to the IoT Platform console, move the pointer over your profile picture, and then click AccessKey Management.

      • Replace $AccountEndpoint with the MNS endpoint. In the MNS console, click Get Endpoint.

    3. Specify the logic that is used to receive device messages.

      MNSClient client = account.getMNSClient(); 
      CloudQueue queue = client.getQueueRef("aliyun-iot-a1wmrZPO8o9"); // Specify the name of the queue that is automatically created. 
          while (true) { 
          // Retrieve messages.  
          Message popMsg = queue.popMessage(10);  // The timeout period of long polling requests is 10 seconds.       
          if (popMsg != null) { 
              System.out.println("PopMessage Body: "+ popMsg.getMessageBodyAsRawString()); // Obtain raw messages.  
              queue.deleteMessage(popMsg.getReceiptHandle()); // Delete the messages from the queue.  
          } else { 
              System.out.println("Continuing"); } }
    4. Run the program to listen to the MNS queue.

  3. Start a device and send a message from the device to IoT Platform.

    For information about how to configure a Link SDK, see the Link SDK documentation.

  4. Check whether the cloud applications can receive the message. If the message is received, the content of the message is similar to the following information.

    "messageid":" ",
    "payload":" ", 
    "timestamp": " "




    The ID of the message. The message ID is generated by IoT Platform.


    The message type of the topic. Valid values:

    • upload: submitted device data

    • status: device status changes

    • topo_listfound: the detection of sub-devices by a gateway

    • topo_lifecycle: device topology changes

    • device_lifecycle: device lifecycle changes

    • thing_history: historical TSL data

    • ota_event: over-the-air (OTA) update status


    The IoT Platform topic from which the message is forwarded.


    The base64-encoded message payload.

    For more information about data formats, see Data formats.


    The timestamp. It is the number of seconds that have elapsed since 00:00:00 Thursday, January 1, 1970.