All Products
Search

This Product

    IoT Platform:Communication messages

    Document Center

    IoT Platform:Communication messages

    Last Updated:Jun 20, 2026

    This topic describes common messaging issues and solutions for communication between devices, the IoT Platform, and servers.

    Category

    Question

    uplink and downlink messages

    Topic subscription

    Message forwarding

    Message storage

    Querying messages

    Handling duplicate messages

    QoS level 1 guarantees at-least-once delivery, so a device may receive duplicate messages. These duplicates will have the same message ID, which a device can use for deduplication. IoT Platform also minimizes sending duplicate QoS level 1 messages.

    MQTT device fails to receive data

    If a device fails to receive data, check the following to identify the cause:

    • Verify that the device is subscribed to the correct topic. An MQTT device can only receive messages from topics to which it has subscribed.

    • If the device intermittently misses messages: Check for time-consuming logic in your device application's callback. If present, move this logic to a separate thread to avoid blocking the callback.

    • Ensure the application subscribes to the topic during its initialization. Messages sent before the subscription is complete may be lost.

    • To receive QoS 1 messages sent while the device was offline, set the MQTT connection parameter cleanSession to false (that is, cleanSession must be false).

    Message storage

    After a message is published to a topic, IoT Platform immediately forwards it to devices subscribed to that topic.

    • QoS 0 message: IoT Platform does not store it.

    • QoS 1 message: IoT Platform stores it for 7 days.

    Device data retention period

    • QoS 0 messages: IoT Platform does not retain them.

    • QoS 1 messages: IoT Platform retains them for 7 days.

    You can view communication logs for the past 7 days in the IoT Platform console on the Monitoring and Operations > Log Service page for your instance. For more information, see Log Service.

    Slow or timed-out message delivery

    An unstable network connection is a common cause of this issue.

    To test the device's network connectivity:

    1. Log on to the IoT Platform console.

    2. On the Overview page, find the instance and click its ID or alias.

    3. In the left-side navigation pane, choose Devices > Devices.

    4. On the Devices page, search for the device by its DeviceName or alias.

    5. In the Actions column for the device, click View.

    6. On the Device Information tab, click Test next to Real-time Delay.

    7. Click OK to begin the test.

    Repeat steps 6 and 7 to gather more data. Consistently high latency indicates an unstable network connection.

    Support for will and retained messages

    Yes. IoT Platform supports will and retained messages with MQTT 5.0. For more information, see MQTT 5.0 features that are supported by IoT Platform.

    Server-side message retrieval

    A server can retrieve device messages in two ways.

    • Server-side subscription: Use IoT Platform's server-side subscription to subscribe to one or more message types. Based on your subscription settings, IoT Platform forwards messages of the specified types from all devices under a product to your server. IoT Platform supports the following types of server-side subscription:

    • Data forwarding: Use data forwarding to route data from specified devices to a Simple Message Queue (formerly MNS) (SMQ) queue or a Message Queue for Apache RocketMQ queue based on data forwarding rules. Your server consumes the messages using an MNS SDK or a Message Queue for Apache RocketMQ SDK. For more information, see Overview of data forwarding.

    Console messages not received by SMQ queues

    IoT Platform does not forward messages sent from the console or via a cloud API to Simple Message Queue (formerly MNS) (SMQ) queues because it considers them server-side messages. Only messages that originate from a device, such as upstream device messages, notifications of device status changes, and device tag changes, are routed to SMQ queues.

    How to identify the source topic

    Messages in a Simple Message Queue (formerly MNS) (SMQ) have the following format:

    {
	"messageid": "12345",
	"messagetype": "status/upload",
	"topic": "null/topic",
	"payload": {},
	"timestamp": 1469564576
}

    The topic field identifies the source topic.

    Send commands to devices

    You can call the following IoT Platform APIs to send messages to devices:

    API

    Description

    Pub

    Sends a message to a specified device using a custom topic.

    BatchPub

    Sends a message to multiple devices of a specified product using a custom topic.

    PubBroadcast

    Broadcasts messages to online devices of a specified product.

    You can target all online devices or only those that subscribe to a specific topic.

    RRpc

    Sends a request message to a specified device and returns a response synchronously.

    SetDeviceProperty

    Sets the value of a Thing Specification Language (TSL) property for a specified device.

    SetDevicesProperty

    Sets the value of a Thing Specification Language (TSL) property for multiple devices of a specified product.

    InvokeThingService

    Invokes a specified Thing Specification Language (TSL) service on a single device.

    InvokeThingsService

    Invokes a specified Thing Specification Language (TSL) service on multiple devices of a specified product.

    Device-to-device communication

    Yes, devices in the same instance can communicate with each other.

    Use the data forwarding or message routing feature to forward messages from one device's topic to another, enabling communication between them.

    QoS 2 message failure

    IoT Platform supports QoS 0 and QoS 1, but does not support QoS 2.

    For details, see the MQTT protocol specification.

    Device connection and status synchronization

    Subscribe to device status update messages using server-side subscription to keep device connection and status information in sync.

    For more information, see Server-side subscription.

    Visualizing device data

    Publish hexadecimal messages via API

    In the IoT Platform console, you cannot send hexadecimal messages using online debug, the device simulator, or the topic list tab on a device's details page.

    You can use the Pub, BatchPub, or PubBroadcast APIs to send hexadecimal messages. The MessageContent parameter must be the Base64-encoded original message, which can be a string or a hexadecimal byte array.

    After your business server sends a message via an API, IoT Platform automatically Base64-decodes the message before forwarding it to the device.

    Export device data

    IoT Platform stores QoS 0 messages for up to 1 day and QoS 1 messages for up to 7 days.

    You can use the data storage feature of Data Service to store offline device data and time-series data. Offline data includes platform system tables, time-series tables, snapshot tables, and custom storage tables. Device time-series data includes Thing Model data (properties, services, and events) reported by devices and custom topic data configured using time-series data storage rules. For more information, see Configure Data Storage.

    • To retrieve device data, use APIs to query the data and push it to your own server.

    • If you need to store device data for extended periods, reduce storage costs, or perform further data processing (such as SQL analysis, and Data API), you can back up device data sources. After you enable data backup for a product, IoT Platform automatically creates corresponding time-series/snapshot tables for the product in offline storage. These tables include the product property time-series table, product property snapshot table, and product event table.

    AMQP subscription for hexadecimal data

    Yes.

    Follow these steps to forward hexadecimal data:

    1. Configure the device to upload data in hexadecimal format by using a custom topic. For more information, see Use custom topics to communicate.

    2. Configure message forwarding to subscribe to device-reported messages on a custom topic.

    3. Use an AMQP client SDK to consume custom messages from the device.

      Alibaba Cloud IoT Platform provides sample code for AMQP SDKs in the following languages:

      The AMQP client SDKs for Python 3 and PHP use the STOMP protocol to communicate with Alibaba Cloud IoT Platform. When you use these SDKs, you must Base64-encode the payload before pushing it. Otherwise, the payload may be truncated.

      For detailed instructions on using the SDKs, see AMQP client connection.

    Consumer group and AMQP message queue mapping

    Yes.

    Up to 128 AMQP clients can consume messages from a single AMQP message queue.

    Mapping a device to a single AMQP queue

    Yes.

    Use the Rule Engine to configure data forwarding to a consumer group that subscribes to an AMQP server. In the message forwarding parser, use functions such as topic(number) or deviceName() in an if statement to select a device and forward its messages to the AMQP message queue.

    Here is a sample parser script:

    // Get the device's message payload and parse it as JSON.
var data = payload("json");
// Get the device name.
var dn = deviceName();
// If the message is from 'device01', forward its data.
if (dn == 'device01') { 
    writeAmqp(1000, data, "Debug");  
}

    To learn more about parser scripts, see Script syntax. For instructions on configuring a message forwarding parser, see Forward data to a consumer group that subscribes to an AMQP server.

    Notify apps of device online status

    The server-side subscription feature of IoT Platform allows you to receive device status change messages. To use this feature, deploy and start an AMQP client on the server that hosts your app or mini program.

    The implementation is as follows:

    1. Configure AMQP server-side subscription: In the IoT Platform console, configure a server-side subscription consumer group to push device status change messages.

    2. AMQP client integration: On the server that hosts your app or mini program, deploy and start an AMQP client to connect to IoT Platform.

      For information about the data format of device status change messages, see Device Online/Offline Status. After the AMQP client receives messages, you must implement the logic to display them in your app or mini program.

    3. Device Connection: After a device connects to IoT Platform, the platform forwards its status information to the AMQP client for consumption.

    Message not received after a Pub API call

    The device is not subscribed to the topic specified in the Pub API call.

    A device must be subscribed to a topic to receive messages from it. To subscribe the device, call the SubscribeTopic API.

    Subscribe to and view topics

    • A device must actively subscribe to topics. Upon successful subscription, the topics appear in the Topic List on the Device details page for your instance in the IoT Platform console.

    • If a device has not subscribed to any topics, the Topic List tab on its details page will be empty.

    Subscribe to topics

    A device can subscribe to topics in the following ways:

    • If you use the C Link SDK (versions 3.1, 3.2, and 4.x) or the Python Link SDK provided by IoT Platform, your device automatically subscribes to basic communication topics and Thing Model topics that have subscribe permission.

      After you create a custom topic with subscribe permission, you can use the following APIs in the SDK to subscribe to the custom topic:

      If you enable proxy subscription when you create a custom topic, IoT Platform automatically subscribes the device to that topic when the device establishes a connection.

      To add a custom topic, see Use custom topics to communicate.

    • Start device simulator: When you use the device simulator feature provided by IoT Platform, the device automatically subscribes to basic communication topics and Thing Model topics.

      After you create a custom topic with subscribe permission, you can use the upstream command debugging feature to subscribe to it.

    • Use MQTT.fx to connect to IoT Platform: After the device is online, use the Subscribe feature to subscribe to device topics.

    • SubscribeTopic: After a device connects to IoT Platform, call this API to subscribe to device topics.

      After you create a custom topic with subscribe permission, you can call the SubscribeTopic API to subscribe to the topic.

    View subscribed topics

    Choose one of the following methods:

    Why can't AMQP subscriptions receive RRPC messages?

    RRPC communication is a synchronous process: the server-side sends a request to a device and waits for a response. IoT Platform does not support AMQP server-side subscriptions for RRPC communication messages.

    For more information about RRPC communication, see MQTT synchronous communication (RRPC).

    Standard JSON format for custom topics

    IoT Platform does not enforce a specific data format for communication over custom topics. You define the format.

    For information about the topics and the required Alink JSON format for communication between devices and IoT Platform, see the Alink protocol documentation.

    If you set the data format to passthrough/custom when you create a Product, you must configure message parsing. This configuration parses custom-formatted payloads, which devices send over a custom topic, into JSON format. For more information, see Custom topic message parsing.

    Thing model communication error: "5092 - property not found"

    This error means a property in an uplink or downlink message is not defined in the thing model.

    Possible causes:

    • The property is not defined in the thing model. Go to the IoT Platform console to review the property definitions and add the required property. See Add a thing model.

    • The property is defined in a custom module. For uplink and downlink communication, you must prefix the property with the custom module's identifier in the following format: {tsl.functionBlockId}:{tsl.properties.identifier}.

    For details on thing model fields, see TSL field reference for the thing model. For more information on message-related error codes, see Error codes in the cloud runtime log.

    Property setting: device response error 6335

    The thing model specifies an empty response for the property setting method. Therefore, when IoT Platform sends a property setting command to a device, the data field in the device response message must be empty. If the data is not empty, an error occurs.

    For more information about error codes, see error codes in cloud-side run logs.

    Topic matching for devices

    Yes. The topics of a physical device must match those of its corresponding device in the product.

    Cross-device topic subscription

    No. A device can only subscribe to its own topics.

    Receive messages from all devices

    You can use AMQP server-side subscription for your server to receive device messages. For more information, see Use AMQP server-side subscription.

    Subscription failure with a shared device certificate

    1. Only one device can use a device certificate at a time. The hardware device and the MQTT client must use different device certificates to connect to IoT Platform.

    2. A device can only subscribe to its own topics and cannot publish messages to the topics of other devices.

    3. You can use Data Forwarding or topic-based message routing to forward messages from one device's topic to another, which enables communication between the devices.

      For example:

    Operation permissions for topics

    • IoT Platform predefines the operation permissions for basic and thing model topics, and you cannot modify them. To view these permissions, follow these steps:

      1. Log in to the IoT Platform console.

      2. In the upper-left corner of the console, select the region where your instance is located.

      3. On the Instance Overview tab, under All Environments, find your instance and click its card.

      4. In the left-side navigation pane, choose Device management > Product.

      5. On the Product page, find your product and click View in the Actions column.

      6. On the Product details page, click the Topic category list tab. You can then view the topic lists on the Basic topic and Thing model topic tabs.

        The Operation permission column in the topic list shows the Publish and Subscribe permissions for each topic.

        The table on the Thing model topic tab contains the Function, Topic category, Operation permission, and Description columns. This table lists the topic paths (such as /sys/${productKey}/${deviceName}/thing/event/property/post) and their corresponding publish or subscribe permissions for functions including report property, set property, report event, and invoke service.

    • Use the QueryProductTopic API to query the details of a product's custom Topic categories.

    Export cloud-side run logs

    No, you cannot.

    • You can activate Log Service and then enable the transfer of cloud-side run logs in the IoT Platform console. This lets you export the logs to a Logstore in Log Service for long-term storage. For instructions, see Transfer cloud-side run logs.

      After you enable the log transfer feature, Log Service automatically creates the following resources to store your logs. You can then view the transferred cloud-side run logs in Log Service.

      • Project: iot-log-${uid}-${regionId}. In this format, ${uid} is your Alibaba Cloud account ID, and ${regionId} is the region ID of your IoT Platform service.

      • Logstore: iot-logs.

    IoT Platform: Deliver a single device message to multiple servers

    For an AMQP server-side subscription, a consumer group is mapped to a single AMQP message queue. If you start multiple consumers and bind them to the same consumer group, each device message is delivered to only one of them at random. To send a copy of every message to each consumer, bind each consumer to a different consumer group.

    For more information, see the following topics:

    Broadcast messages to multiple devices

    The IoT platform's PubBroadcast interface allows you to publish a broadcast message to multiple online devices within a specific product. You can target all online devices or only those that subscribe to a specified topic.

    IoT Platform server-side subscription error 9203

    This error occurs because the AMQP client or Simple Message Queue (formerly MNS) (SMQ) client for the server-side subscription is offline. To connect the AMQP client, see Connect an AMQP client. To connect the MNS client, see Develop an MNS consumer client.

    Device subscription frequency

    While a device only needs to subscribe once, we recommend subscribing every time it powers on. This ensures the corresponding callback in your code is triggered.

    Sending messages before subscription

    No. A device receives messages from a communication topic only after subscribing to it. For details, see Use communication topics.

    Connect a client and subscribe to property changes

    1. Configure an AMQP server-side subscription: In IoT Platform, set the Message Type to Device-reported Messages.

    2. Use an AMQP client SDK to connect to IoT Platform and receive subscribed Device-reported Messages containing device property data.

      Alibaba Cloud IoT Platform provides AMQP client SDK sample code in the following languages:

      The AMQP client SDKs for Python 3 and PHP use the STOMP protocol to communicate with IoT Platform. When using these SDKs, you must Base64-encode the message content before pushing it. Otherwise, the message content may be truncated.

      For detailed instructions on using the SDKs, see AMQP client connection instructions.

    Cross-account authorization

    • Use device distribution to distribute devices from a source instance to a target instance in another account. The target account can then view data from these devices. For usage limits and detailed instructions, see device distribution.