Message Push Interface (Trait)
Subscribe To Trait Value
- API intent: spec.config.trait.subscribe
- Description: This API is used to subscribe to real-time changes of device traits. When the value of a device trait changes, the Aqara server will push the latest data to you through this interface. Subscription is based on the message push function. For message push details, please refer to message push.
Request Parameter Description
| Name |
Type |
Required |
Description |
| traits |
Array<Object> |
Yes |
Array of traits to subscribe to. |
| traits[].subjectId |
String |
Yes |
ID of the device to subscribe to. |
| traits[].codePaths |
Array<String> |
Yes |
Array of trait path strings. The format is: endpointId.functionCode.traitCode. |
| traits[].attach |
String |
No |
Additional information, transparently transferred to the subscription notification message body. |
Request Example
{
"intent": "spec.config.trait.subscribe",
"data": {
"traits": [
{
"subjectId": "matt.11774113824794",
"codePaths": [
"2.Output.OnOff", "3.Output.OnOff"
],
"attach": "haha"
}
]
}
}
Response Data Description
None
Response Example
{
"code": 0,
"message": "Success",
"msgDetails": null,
"requestId": "",
"result": null
}
Receive Trait Update Messages
Message Parameter Description
| Field |
Type |
Description |
| data |
Array<Object> |
Array of changed trait data. |
| data[].codePath |
String |
Path of the changed trait, in the format endpointId.functionCode.traitCode. |
| data[].model |
String |
Device model. |
| data[].statusCode |
Number |
Status of the change, indicating success or failure. See Trigger Results for details. |
| data[].subjectId |
String |
Unique identifier of the device. |
| data[].time |
String |
UTC timestamp in milliseconds when the trait changed. |
| data[].triggerSource |
Object |
The reason why the message was triggered. |
| data[].triggerSource.time |
String |
The trigger time (UTC timestamp in seconds) causing the message to change. |
| data[].triggerSource.type |
Number |
Type of message trigger, see Trigger Types for details. |
| data[].value |
Any |
The new value of the trait, type depends on the specific trait. |
| data[].attach |
String |
Additional info transparently transferred from subscription. |
| msgId |
String |
Unique message identifier. |
| msgType |
String |
Message type, always spec_report. |
| openId |
String |
Unique user identifier. |
| time |
String (Number) |
UTC timestamp in milliseconds when the message was produced. |
Message Example
{
"data": [
{
"codePath": "2.Contact.ContactSensorState",
"model": "aqara.matter.4447_8194",
"statusCode": 0,
"subjectId": "matt.2990fb3413ed87c9b7370000",
"time": "1762430871166",
"triggerSource": {
"time": "1762430871",
"type": 10
},
"value": "1",
"attach": "openSpec"
}
],
"msgId": "FD0CC3DE8CAC55F881F84802DAD15F54A36C2ACF57E321068AAE001A1",
"msgType": "spec_report",
"openId": "695771340211436040058973585409",
"time": "1762480476859"
}
Unsubscribe from trait value
- API intent: spec.config.trait.unsubscribe
- Description: This API is used to unsubscribe from real-time updates of device trait data.
Request Parameter Description
| Parameter |
Type |
Required |
Description |
| traits |
Array<Object> |
Yes |
Array of target traits. |
| traits[].subjectId |
String |
Yes |
Target device ID. |
| traits[].codePaths |
Array<String> |
Yes |
Array of target function code paths in the format endpointId.functionCode.traitCode. |
Request Example
{
"intent": "spec.config.trait.unsubscribe",
"data": {
"traits": [
{
"subjectId": "matt.11774113824794",
"codePaths": [
"2.Output.OnOff","3.Output.OnOff"
]
}
]
}
}
Response Data Description
None
Response Example
{
"code": 0,
"message": "Success",
"msgDetails": null,
"requestId": "",
"result": null
}