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. IoT Platform automatically forwards messages to MNS queues.
    1. Log on to the IoT Platform console.
    2. On the Overview page, find the instance that you want to manage and click the instance name to go to the Instance Details page.
      Important Enterprise Edition instances are available in the China (Shanghai) and Japan (Tokyo) regions. If the Enterprise Edition instances are unavailable in the region that you select, skip this step.
    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.
      ProductSelect the product to which the devices belong. The messages submitted by the devices are pushed to consumers.
      Subscription TypeSelect MNS.
      Message TypeSelect the types of messages. You can subscribe to the following types of device messages:
      • Device Upstream Notification: these 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 about data formats, 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. When a device update succeeds or fails, a notification is pushed.
    6. In the message that appears, click Confirm.
      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.

      Note 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.

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

    For information about how to download the MNS 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 MNS SDK:
      CloudAccount account = new CloudAccount( $AccessKeyId, $AccessKeySecret, $AccountEndpoint);
      • Replace $AccessKeyId and $AccessKeySecret with the AccessKey ID and AccessKey secret of your Alibaba Cloud account. These 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 automatically created queue. 
          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 use a Link SDK to configure a device, see the Link SDK documentation.

  4. Check whether your cloud application retrieves the message. The following code shows the format of a retrieved message:
    "messageid":" ",
    "payload":" ", 
    "timestamp": " "
    messageidThe ID of the message. The message ID is generated by IoT Platform.
    messagetypeThe type of the message. Default value: false. 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
    topicThe IoT Platform topic from which the message is forwarded.
    payloadThe base64-encoded message payload.

    For more information about data formats, see Data formats.

    timestampThe timestamp. It is the number of seconds that have elapsed since the epoch time January 1, 1970, 00:00:00 UTC.