Updated on 2023-02-02 GMT+08:00

Custom Topic Communications


The IoT platform uses topics to communicate with devices over MQTT. There are custom topics and system topics. System topics are basic communication topics preconfigured on the platform. You can also customize topics on the platform based on service requirements.


  • Devices publish messages to a custom topic, from which an application receives the messages using the data forwarding function.
  • An application calls the API for delivering a message to a device to publish messages to a specified custom topic. Devices subscribe to this topic to receive messages from the server.

Topic Categories



System topic

The platform predefines topics for communications with devices. For details on the topic list and functions, see system topics.

Custom topic

Devices and the platform can communicate based on custom topics.

Types of custom topics:

  • Topics defined in the product are prefixed with $oc/devices/{device_id}/user/. During message reporting or delivery, the platform checks whether the topic is defined in the product. Undefined topics will be rejected by the platform. For details about how to use this type of topics, see Using a Custom Topic for Communication.
  • Custom topics that do not start with $oc, for example, /aircondition/data/up, are used for message communications. The platform does not check the topic permission. This type of topics enables upstream and downstream message communications based on MQTT rules. For details, see Migrating a Custom Topic to the Cloud.


You can define a maximum of 50 custom topics for a product model.


  1. Access the IoTDA service page and click Access Console.
  2. Select an MQTT product. On the product details page, click the Topic Management tab, select Custom Topic, and click Add Topic.
  3. In the dialog box displayed, select device operation permissions and enter the topic name.




    The topic prefix is fixed at $oc/devices/{device_id}/user/. Replace {device_id} with the actual device ID during publishing and subscription. A custom topic must be in a slash-separated format.

    The value can contain 1 to 64 characters. Only digits, letters, underscores (_), and non-consecutive slashes (/) are allowed.

    Note: Custom topics do not support custom variables. For example, {type} in $oc/devices/{device_id}/user/setting/{type} is a variable and is not supported.

    Device Operation Permissions

    • Publish: Devices can report messages using this topic. A topic is carried in a device message during data transfer for better classification.

    • Subscription: Devices can receive messages using this topic. The platform can deliver messages to devices by topic.

    • Publish and subscription: Devices can report and receive messages using this topic.


    Provide a description of the topic.

  4. Click OK.

    After the topic is added, you can modify or delete it in the custom topic list.

For details about how to use custom topics, see Using a Custom Topic for Communication. If a topic prefixed with $oc/devices/{device_id}/user/ cannot be used, you need to customize a topic. For details, see Migrating a Custom Topic to the Cloud.