Broadcasts messages to online devices of a product. You can specify all online devices or only the online devices that subscribe to a specified topic.

Usage notes

You can use the TopicFullName parameter in the request to specify the devices to which you want to broadcast messages. For more information, see the description about the TopicFullName parameter in this topic.

QPS limits

  • Each Alibaba Cloud account can run only one query per second (QPS) to broadcast a message to devices that subscribe to a topic.
  • Each Alibaba Cloud account can run only one query per minute (QPM) to broadcast a message to all online devices of a product.
    Note The RAM users of an Alibaba Cloud account share the quota of the account.

Debugging

OpenAPI Explorer automatically calculates the signature value. For your convenience, we recommend that you call this operation in OpenAPI Explorer. OpenAPI Explorer dynamically generates the sample code of the operation for different SDKs.

Request parameters

Parameter Type Required Example Description
Action String Yes PubBroadcast

The operation that you want to perform. Set the value to PubBroadcast.

MessageContent String Yes aGVsbG93b3JsZA

The message body that you want to send. The maximum size of a message is 64 KB.

To generate a message body, you must convert the raw message into binary data and perform Base64 encoding.

ProductKey String Yes aldeji3*****

The ProductKey of the product to which the devices belong.

A ProductKey is the unique identifier of a product in IoT Platform. You can view the information about all products within the current Alibaba Cloud account in the IoT Platform console or by calling the QueryProductList operation.

IotInstanceId String No iot_instc_pu****_c*-v64********

The ID of the instance. You can view the ID of the instance on the Overview page in the IoT Platform console.

Notice
  • If your instance has an ID, you must specify this parameter. Otherwise, the call fails.
  • If the Overview page or an instance ID is not displayed in the IoT Platform console, ignore this parameter.

For more information, see Overview.

TopicFullName String No /broadcast/UPqSxj2vXXX/xxx

The name of the topic. This parameter is optional.

  • If you do not specify this parameter, the message is pushed to all online devices that have the specified ProductKey. Devices receive the message from the broadcast topic in the following format: /sys/${productKey}/${deviceName}/broadcast/request/${MessageId}. The MessageId variable is generated by IoT Platform.
  • If you specify this parameter, the message is pushed to the devices that have the specified ProductKey and subscribe to the specified topic. You must specify a broadcast topic by using the following syntax: /broadcast/${productKey}/Custom field. Replace ${productKey} with the ProductKey of the devices that receive the message. For the custom field, you can specify a value based on your business requirements.
Note
  • When you develop devices, you need to only write code to define a broadcast topic. You do not need to create a topic in the IoT Platform console.
  • A maximum of 1,000 devices can subscribe to a broadcast topic. If the number of devices exceeds the limit, you can divide the devices into groups. For example, you can divide 5,000 devices into five groups that contain 1,000 devices. In this case, you must call this operation five times and set the value of the custom field to group1, group2, group3, group4, and group5. Then, configure the devices. This way, each group of devices subscribes to the corresponding topic.

In addition to the preceding operation-specific request parameters, you must specify common request parameters when you call this operation. For more information, see Common parameters.

Response parameters

Parameter Type Example Description
Code String iot.system.SystemException

The error code returned if the call fails. For more information, see Error codes.

ErrorMessage String A system exception occurred.

The error message returned if the request fails.

MessageId Long 1234291569964771840

The message ID that is generated by IoT Platform when the message is sent.

RequestId String BB71E443-4447-4024-A000-EDE09922891E

The ID of the request. The ID is a unique identifier of the request.

Success Boolean true

Indicates whether the call was successful. Valid values:

  • true: The call was successful.
  • false: The call failed.

Examples

Sample requests

https://iot.cn-shanghai.aliyuncs.com/?Action=PubBroadcast
&ProductKey=al**********
&TopicFullName=/broadcast/UPq****/xxx
&MessageContent=aGVsbG93b3JsZA
&<Common request parameters>

Sample success responses

XML format 

<PubBroadcastResponse>
        <RequestId>BB71E443-4447-4024-A000-EDE09922891E</RequestId>
        <MessageId>1234291569964771840</MessageId>
        <Success>true</Success>
  </PubBroadcastResponse>

JSON format 

{
      "RequestId":"BB71E443-4447-4024-A000-EDE09922891E",
      "MessageId":1234291569964771840,
      "Success":true
}