The content of this page has been automatically translated by AI. If you encounter any problems while reading, you can view the corresponding content in Chinese.
Help & Documentation>IoT Explorer>Legacy Document>Application Side API>Long Connection Communication>Device Status Push

Device Status Push

Last updated: 2025-04-30 16:22:04

On this page:

1. API Description

api request domain name: wss://iot.cloud.tencent.com/iotstudio_v2_weapp_1
Device status push is used to obtain the online and offline status of user-bound devices, attributes and events reported by devices, and execution results of device behaviors in real time in mini programs or apps. It is required to successfully call the registered device listening API and obtain real-time push of device status and attribute values through listening to WebSocket's OnMessage. If the obtained event.data.push is true, it signifies that the message is a proactive push of device status change.

2. Input Parameter

Name
Type
Description
push
Boolean
This message is a proactive push for device status change.
action
String
Fixed as DeviceChange, representing device status change.
params
String
Return device information. See detailed explanation in message type description.

3. Output Parameters

Name
Type
Description
RequestId
String
Request ID.

4. Example

Application Side ws Subscription to Device Status Change

Request Sample
  ws.onmessage = (event) => {
    let data;
    try {
      data = JSON.parse(event.data);
    } catch (e) {
      console.log(`onMessage parse event.data error: ${event.data}`);
      return;
    }

    if (data.push) {
      this.emit('push', data);
    } else if (typeof data.reqId !== 'undefined' && this.requestHandlerMap.has(data.reqId)) {
      this.requestHandlerMap.get(data.reqId)(null, data);
    }
  };
Input Parameter Example:
{
	"action": "DeviceChange",
	"params": {
		"Time": "2023-07-13T14:19:48+08:00",
		"Type": "Property",
		"SubType": "Report",
		"Topic": "$thing/up/property/productId/deviceName",
		"Payload": "ey******iOjQwfX0=",
		"Seq": 1689229188406,
		"DeviceId": "productId/deviceName"
	},
	"push": true
}
Output Example: Succeed
{
	"Response": {
		"RequestId": "up03"
	}
}

5. Parameter Descriptions

Parameter Name
Parameter Type
Description
Time
String
Time, in UTC format, for example: 2023-07-13T14:19:48+08:00.
Type
String
Message type. See Type description.
SubType
String
Message subtype. See SubType description.
Topic
String
Message Topic. Log in to IoT Explorer Console and enter the target product development page. Select Device Development > Topic List to view.
Payload
String
Message body base64 encoded content. See Payload description.
Seq
Int64
Serial number.
DeviceId
String
Device ID, product ID in deviceName format.

Type Description

Type
Description
StatusChange
Device status change message, including device online and offline notification.
Shadow
Shadow messages.
Property
Attribute message.
Template
Thing model message.
Event
Event message.
Action
Behavior message.
UserDefined
Custom.

SubType Description

SubType
Description
Online
Device goes online.
Offline
Device offline.
Report
Device reporting.
Push
Server push to device.

Payload Description

Payload is the string literal of the message body after base64 encoding. An example is as follows:
Message Body
 {
	"method": "control",
	"clientToken": "12345678",
	"params": {
		"switch": 0
	}
}
base64 Encoding
"Payload": "eyJtZXRob2QiOiJjb250cm9sIiwiY2xpZW50VG9rZW4iOiIxMjM0NTY3OCIsInBhcmFtcyI6eyJzd2l0Y2giOjB9fQ=="

Template Message Example

The Thing Model message Topic is empty. Payload is the content of the message after base64 encoding.
 {
	"action": "DeviceChange",
	"params": {
		"Time": "2023-07-13T15:00:11+08:00",
		"Type": "Template",
		"SubType": "Push",
		"Topic": "",
		"Payload": "eyJtZXRob2QiOiJjb250cm9sIiwiY2xpZW50VG9rZW4iOiIxMjM0NTY3OCIsInBhcmFtcyI6eyJzd2l0Y2giOjB9fQ==",
		"Seq": 1689231611907,
		"DeviceId": "productId/deviceName"
	},
	"push": true
}
base64 decoded message body of the Payload
See detailed explanation in Thing Model.
 {
	"method": "control",
	"clientToken": "12345678",
	"params": {
		"switch": 0
	}
}

Event Message Example

  {
    "Time": "2019-04-11T20:42:36+08:00",
    "Type": "Event",
    "SubType": "Report",
    "Topic": "$thing/up/event/US4CJ11DIK/LIAO",
    "Payload": "ewogICAgICAgICJtZXRob2QiOiAiZXZlbnRfcG9zdCIsCiAgICAgICAgInZlcnNpb24iOiAiMS4wIiwKICAgICAgICAiZXZlbnRJZCI6ICJsb3dfdm9sdGFnZSIsCiAgICAgICAgInBhcmFtcyI6IHsKICAgICAgICAgICAgInZvbHRhZ2UiOiAyLjI3ODA4MQogICAgICAgIH0sCiAgICAgICAgImNsaWVudFRva2VuIjogImNsaWVudFRva2VuLTU1OSJ9",
    "Seq": 300,
    "DeviceId": "US4CJ11DIK/LIAO"
  }
base64-decode the message body of the Payload
  {
    "method": "event_post",
    "version": "1.0",
    "eventId": "low_voltage",
    "params": {
      "voltage": 2.278081
    },
    "clientToken": "clientToken-559"
  }

Attribute Message Example

  {
    "Time": "2019-10-30T10:41:00+08:00",
    "Type": "Property",
    "SubType": "Report",
    "Topic": "$thing/up/property/WTJTZX0MF2/device_property001",
    "Payload": "eyJ0aW1lc3RhbXAiOiAwLCAicGFyYW1zIjogeyJicmlnaHRuZXNzIjogNTl9LCAibWV0aG9kIjogInJlcG9ydCIsICJjbGllbnRUb2tlbiI6ICJ0bTIwMTkxMDMwMTA0MDUzXzEifQ==",
    "Seq": 6,
    "DeviceId": "WTJTZX0MF2/device_property001"
  }
base64 decoded message body of the Payload
  {
    "method": "report",
    "params": {
      "timestamp": 0,
      "params": {
        "brightness": 59
      },
      "method": "report",
      "clientToken": "tm20191030104053_1"
    }
  }

Status Change Message Example

Device online message.
  {
    "Time": "2019-03-28T15:17:33+08:00",
    "Type": "StatusChange",
    "SubType": "Online",
    "Topic": "",
    "Payload": "",
    "Seq": 6
  }
Device offline.
  {
    "Time": "2019-03-28T15:17:33+08:00",
    "Type": "StatusChange",
    "SubType": "Offline",
    "Topic": "",
    "Payload": "",
    "Seq": 7
  }

Action: Sample Behavior

Sample push for Action message
  {
    "Time": "2021-05-13T21:34:05+08:00",
    "Type": "Action",
    "SubType": "Push",
    "Topic": "",
    "Payload": "eyJtZXRob2QiOiJhY3Rpb24iLCJjbGllbnRUb2tlbiI6IjEzNjk0NzQ5Mzo6cmVxXzEiLCJhY3Rpb25JZCI6ImxpZ2h0X2JsaW5rIiwidGltZXN0YW1wIjoxNjIwOTEyODQ1LCJwYXJhbXMiOnsiY29sb3IiOjEsInRpbWUiOjYsInRvdGFsX3RpbWUiOjYwfX0K",
    "Seq": 1620912845,
    "DeviceId": "0CPSFIRP28/testble"
  }
base64 decoded message body of the Payload
  {
    "method": "action",
    "clientToken": "136947493::req_1",
    "actionId": "light_blink",
    "timestamp": 1620912845,
    "params": {
      "color": 1,
      "time": 6,
      "total_time": 60
    }
  }
Action message report example
  {
    "Time": "2021-05-13T21:34:05+08:00",
    "Type": "Action",
    "SubType": "Report",
    "Topic": "",
    "Payload": "eyJtZXRob2QiOiJhY3Rpb25fcmVwbHkiLCJjbGllbnRUb2tlbiI6IjEzNjk0NzQ5Mzo6cmVxXzEiLCJjb2RlIjowLCJzdGF0dXMiOiJzdWNjIiwicmVzcG9uc2UiOnsicmVzdWx0IjogMX19",
    "Seq": 1620912845,
    "DeviceId": "0CPSFIRP28/testble"
  }
base64 decoded message body of the Payload
  {
    "method": "action_reply",
    "clientToken": "136947493::req_1",
    "code": 0,
    "status": "succ",
    "response": {
      "result": 1
    }
  }


中国站 - English