PubBroadcast - IoT Platform

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

Usage notes

You can set TopicFullName in the request to specify the devices to which you want to broadcast the message. For more information, see the description of the TopicFullName parameter in this topic.

QPS limits

You can call this operation up to 1 time per second per account to broadcast a message to online devices that subscribe to a specific topic.
You can call this operation up to 1 time per minute per account to broadcast a message to all online devices of a product.

Note

The Resource Access Management (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 content that you want to send. The size of a message cannot exceed 64 KB. To generate the message content, convert the raw message into binary data and perform Base64 encoding. Note IoT Platform decodes data by using the Base64 algorithm and then sends the decoded message to the device. This way, the device does not need to decode the Base64-encoded data.
ProductKey	String	Yes	aldeji3*****	The ProductKey of the product to which the devices belong. The ProductKey is a unique identifier issued by IoT Platform to the product. 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 instance ID. You can view the instance ID on the Overview page in the IoT Platform console. Important If your instance has an ID, you must specify this parameter. Otherwise, the request fails. If no Overview page or ID is generated for your instance, you do not need to specify this parameter. For more information, see Overview.
TopicFullName	String	No	/broadcast/UPqSxj2vXXX/xxx	The topic name. 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 5 groups. Each group contains 1,000 devices. In this case, you must call the PubBroadcast operation five times. Each time you call the operation, set the custom field in the broadcast topic to group1, group2, group3, group4, and group5. Make sure that each group of devices subscribes to the specified broadcast 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 request failed. For more information, see the Error codes section of this topic.
ErrorMessage	String	A system exception occurred.	The error message returned if the request failed.
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 request ID.
Success	Boolean	true	Indicates whether the request was successful. Valid values: true false

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
}

Error codes

For a list of error codes, see Service error codes.