Message Types

Last Updated on : 2024-12-30 06:43:16download

Tuya’s IoT message queue is composed of messages generated by the cloud-based business data flow. Tuya defines bizCode (action) to distinguish different messages. For example, the bizCode of device property reporting is devicePropertyMessage. This topic describes the transfer process of typical bizCode and the detailed data format of all available bizCode.

Format description

The data format of a message queue is divided into two layers:

The first layer:
- protocol: the protocol number.
- pv: the protocol version number.
- t: the system time pushed to you.
- data: the business data pushed to you.
- sign: the message signature used for anti-counterfeiting verification. The most critical protocol is a classification with a coarser granularity than bizCode, helping you complete preliminary message distribution.
The second layer: data. This layer can be used only after you decrypt it, and you can get a key-value pair in JSON string format.

The following figure shows the two-layer data format.

Both #msg and the decrypted #msg.data are in JSON format.
With business upgrades, Tuya might add key-value pairs to #msg and #msg.data in JSON format. Make sure that your code processing logic is not affected when key-value pairs are added.

List of protocol numbers

In a message queue, each protocol number stands for different features.

Select the version of protocol numbers

This topic lists two versions of protocol numbers.

IoT Core protocol number: Tuya upgraded the IoT Core service on June 20, 2023. For more information, see the API Adjustment Announcement. The new version includes common underlying APIs related to devices and space, and also provides a matching messaging protocol.
Legacy protocol numbers: including protocol numbers of messages for homes, assets, and some vertical fields.

For example, deviceOnline sent by IoT Core protocol number 1001 and online pushed by the legacy protocol number 20 both indicate that the device is online, but the content of the pushed data varies.

You can choose a messaging protocol based on the specific cloud service. Configuring two protocols might cause duplicate reception and processing. If you want to simultaneously use both versions of messages, see Set up messaging rules to configure message reception.

IoT Core protocol number

Service	Protocol number	bizCode	Scope of application
Device data reporting	1000	`devicePropertyMessage`: Report device properties. `deviceQueryPropertyMessage`: Query and report device properties. `deviceEventMessage`: Report device events. `deviceActionResponseMessage`: Invoke device actions.	IoT Core
Device management	1001	`deviceOnline`: A device goes online. `deviceOffline`: A device goes offline. `deviceTransfer`: Transfer a device. `deviceFreeze`: Freeze a device. `deviceUnFreeze`: Unfreeze a device. `deviceBindSpace`: Bind a device. `deviceUnbindSpace`: Unbind a device. `deviceNameUpdate`: Rename a device.	IoT Core
Device OTA updates	1002	`deviceOtaProgress`: Device firmware OTA updates are in progress.	IoT Core
Space	1010	`spaceCreate`: Create a space. `spaceRemove`: Remove a space. `spaceUpdate`: Rename a space.	IoT Core
Group	1020	`groupCreate`: Create a group. `groupDelete`: Remove a group. `groupNameUpdate`: Rename a group. `groupDeviceAdd`: Add a device to a group. `groupDeviceRemove`: Remove a device from a group.	IoT Core
Linkage rule	1030	`linkageRuleChangeComplete`: Change a linkage rule. `linkageRuleExecuteComplete`: Execute a linkage rule.	IoT Core

Legacy protocol number

The legacy protocol numbers are for your reference.

Service	Protocol number	bizCode	Scope of application
Device data reporting	4	`statusReport`: Report device status data.	Legacy version
Device management	20	`online`: A device goes online. `offline`: A device goes offline. `nameUpdate`: Rename a device. `dpNameUpdate`: Rename a data point of a device. `bindUser`: Bind a device with a user. `delete`: Remove a device. `upgradeStatus`: Update status of a device.	Legacy version
IoT SIM card	43	`simStop`: Suspend an IoT SIM card. `simLimitAlarm`: Send data usage alerts of an IoT SIM card.	Legacy version
Third-party speaker	45	`textToSpeech`: Trigger a voice prompt. `reset`: Reset a third-party speaker. `customQAChange`: Change the custom Q&A data.	Legacy version
Automation	25	`automationExecute`: Run an automation task. `automationEnable`: Enable an automation task. `automationUpdate`: Modify an automation task. `automationAdd`: Add an automation task. `automationDisable`: Disable an automation task. `automationRemove`: Remove an automation task.	Legacy version
Automate an external action	22	`automationExternalAction`: Automate an external action.	Legacy version
Scene	25	`sceneAdd`: Add a scene. `sceneUpdate`: Modify a scene. `sceneRemove`: Remove a scene. `sceneEnable`: Enable a scene. `sceneDisable`: Disable a scene. `sceneExecute`: Run a scene. `scenesStrategyModify`: Modify scene rules.	Legacy version
Industrial asset	13001	`industryAssetDeviceBind`: Bind a device with an industrial asset. `industryAssetDeviceUnbind`: Unbind a device from an industrial asset. `industryAssetChange`: Change an industrial asset.	Legacy version
Security device	30	`preArm`: Arming. `armed`: Armed. `disarm`: Disarm. `preAlarm`: Start the alarm delay. `cancelAlarm`: Cancel an alarm.	Legacy version
Infrared product	50	`infraredLearnMessage`: Push messages about infrared learning and saving.	Legacy version
Notification of device information	20	`event_notify`: Modify the device information.	Legacy version
User property	32	`userProperty`: Modify a user’s extension property.	Legacy version
Geofencing	40	`outdoorsFenceAlarm`: Trigger an alarm by the electronic geofence.	Legacy version
User event	54	`userRegisterEvent`: Register a user. `userUpdateEvent`: Modify a user. `userDeleteEvent`: Delete a user. Currently, a user deletion message is sent seven days after the user is deleted.	Legacy version
Home event	35	`homeCreate`: Create a home. `homeUpdate`: Modify a home. `homeDelete`: Delete a home. `homeMemberSharing`: Invite a home member. `homeMemberUpdate`: Modify a home member. `homeMemberDelete`: Delete a home member.	Legacy version
Room event	34	`roomCreate`: Create a room. `roomBatchCreate`: Create rooms in bulk. `roomDelete`: Delete a room. `roomSort`: Sort a room. `roomNameUpdate`: Rename a room.	Legacy version

IoT Core events

Report device data (protocol 1000)

Report device properties

Description of bizData

code	Data type	Description
dataId	String	The unique ID of the reported data. This ID has no business meaning.
devId	String	The device ID.
productId	String	The product ID of the specified device.
properties	List<PropertyItem>	The list of the device property data reported this time.

Description of PropertyItem

code	Data type	Description
code	String	The code of the reported device property.
value	String	The value of the reported device property.
dpId	String	The ID of the specified data point.
time	Long	The 13-digit timestamp when the device property was reported.

Example

{
    "bizCode": "devicePropertyMessage",
    "bizData": {
        "dataId": "1635186469981261***",
        "devId": "263a15c90bc83eff35***",
        "productId": "ejhcgtdtgtcuh***",
        "properties": [
            {
                "code": "property",
                "dpId": 101,
                "time": 1678693809396,
                "value": "red"
            }
        ]
    },
    "ts": 1678693809396
}

Instruct device to report properties

Different from the action that a device regularly reports device properties, the cloud or mobile app actively sends an instruction to a device to trigger status reporting. After receiving the specified instruction, the device reports the required status.

Description of bizData

code	Data type	Description
dataId	String	The unique ID of the reported data. This ID has no business meaning.
devId	String	The device ID.
productId	String	The product ID of the specified device.
properties	List<PropertyItem>	The list of the device property data reported this time.

Description of PropertyItem

code	Data type	Description
code	String	The code of the reported device property.
value	String	The value of the reported device property.
dpId	String	The ID of the specified data point.
time	Long	The 13-digit timestamp when the device property was reported.

Example

{
    "bizCode": "deviceQueryPropertyMessage",
    "bizData": {
        "dataId": "1635186469981261***",
        "devId": "263a15c90bc83eff35***",
        "productId": "ejhcgtdtgtcuh***",
        "properties": [
            {
                "code": "property",
                "dpId": 101,
                "time": 1678693809396,
                "value": "red"
            }
        ]
    },
    "ts": 1678693809396
}

Report device events

Description of bizData

code	Data type	Description
dataId	String	The unique ID of the reported data. This ID has no business meaning.
devId	String	The device ID.
productId	String	The product ID of the specified device.
eventCode	String	The code of the specified device event.
time	Long	The 13-digit timestamp when the device event was reported.
outputParams	List<OutputParamsItem>	The list of the device event data reported this time.

Description of OutputParamsItem

code	Data type	Description
code	String	The name of the specified output parameter.
value	String	The value of the specified output parameter.

Example

{
    "bizCode": "deviceEventMessage",
    "bizData": {
        "dataId": "1635186587996393***",
        "devId": "263a15c90bc83eff35***",
        "eventCode": "event",
        "outputParams": [
            {
                "code": "event_1",
                "value": "true"
            }
        ],
        "productId": "ejhcgtdtgtcuh***",
        "time": 1678693837533
    },
    "ts": 1678693837789
}

Invoke device actions

Description of bizData

code	Data type	Description
dataId	String	The unique ID of the reported data. This ID has no business meaning.
devId	String	The device ID.
productId	String	The product ID of the specified device.
actionCode	String	The code of the specified device action.
time	Long	The 13-digit timestamp when the device action was invoked.
responseCode	String	The returned result. Valid values: `0`: success. Other values: failure.
status	String	The execution status of the specified action. Valid values: `SUCCESS`: success. `TIME_OUT`: timeout.

Example

{
    "bizCode": "deviceActionResponseMessage",
    "bizData": {
        "actionCode": "action_code",
        "dataId": "1443433584600440***",
        "devId": "263a15c90bc83eff35***",
        "productId": "ejhcgtdtgtcuh***",
        "responseCode": 0,
        "status": "SUCCESS",
        "time": 1678693877497
    },
    "ts": 1678693878088
}

Manage device (protocol 1001)

Go online

Description of bizData

code	Data type	Description
devId	String	The device ID.
productId	String	The product ID of the specified device.
uid	String	The ID of the user who performs device pairing.
time	Long	The 13-digit timestamp when the device went online.

Example

{
    "bizCode": "deviceOnline",
    "bizData": {
        "devId": "6c0946b2fff7b98d6em***",
        "uid": "ay1638425579033A1***",
        "productId": "jv19g49qohpo8***",
        "time": 1678952060301
    },
    "ts": 1678952060418
}

Go offline

Description of bizData

code	Data type	Description
devId	String	The device ID.
productId	String	The product ID of the specified device.
uid	String	The ID of the user who performs device pairing.
time	Long	The 13-digit timestamp when the device went offline.

Example

{
    "bizCode": "deviceOffline",
    "bizData": {
        "devId": "6c0946b2fff7b98d6em***",
        "uid": "ay1638425579033A1***",
        "productId": "jv19g49qohpo8***",
        "time": 1678951891724
    },
    "ts": 1678951891733
}

Transfer a device

Description of bizData

code	Data type	Description
devId	String	The device ID.
productId	String	The product ID of the specified device.
spaceId	String	The ID of the specified target space.
fromSpaceId	String	The ID of the specified source space.

Example

{
    "bizCode": "deviceTransfer",
    "bizData": {
        "devId": "6c0946b2fff7b98d6em***",
        "spaceId": "151481***",
        "productId": "jv19g49qohpo8***",
        "fromSpaceId": "151482***"
    },
    "ts": 1678952218298
}

Freeze a device

Description of bizData

code	Data type	Description
devId	String	The device ID.
productId	String	The product ID of the specified device.
uid	String	The ID of the user who performs device pairing.
spaceId	String	The ID of the specified space.

Example

{
    "bizCode": "deviceFreeze",
    "bizData": {
        "devId": "6c0946b2fff7b98d6em***",
        "uid": "ay1638425579033A1***",
        "spaceId": "151481***",
        "productId": "jv19g49qohpo8***"
    },
    "ts": 1678952317535
}

Unfreeze a device

Description of bizData

code	Data type	Description
devId	String	The device ID.
productId	String	The product ID of the specified device.
uid	String	The ID of the user who performs device pairing.
spaceId	String	The ID of the specified space.

Example

{
    "bizCode": "deviceUnFreeze",
    "bizData": {
        "devId": "6c0946b2fff7b98d6em***",
        "uid": "ay1638425579033A1***",
        "spaceId": "151481***",
        "productId": "jv19g49qohpo8***"
    },
    "ts": 1678952314832
}

Bind a device

Description of bizData

code	Data type	Description
devId	String	The device ID.
productId	String	The product ID of the specified device.
uid	String	The ID of the user who performs device pairing.
spaceId	String	The ID of the specified space.
uuid	String	The universally unique identifier (UUID) of the specified device.
token	String	The token for device pairing.

Example

{
    "bizCode": "deviceBindSpace",
    "bizData": {
        "devId": "6c0946b2fff7b98d6em***",
        "uid": "ay1638425579033A1***",
        "spaceId": "151481***",
        "productId": "jv19g49qohpo8***",
        "uuid": "ca4ad1cb06be1***",
        "token": "RuUWe***"
    },
    "ts": 1678952059739
}

Unbind a device

Description of bizData

code	Data type	Description
devId	String	The device ID.
productId	String	The product ID of the specified device.
uid	String	The ID of the user who performs device pairing.
spaceId	String	The ID of the specified space.
sub	String	Specifies whether it is a sub-device. Valid values: `true`: yes `false`: no
resetFactory	String	Specifies whether to restore factory defaults.
uuid	String	The universally unique identifier (UUID) of the specified device.

Example

{
    "bizCode": "deviceUnbindSpace",
    "bizData": {
        "devId": "6c0946b2fff7b98d6em***",
        "uid": "ay1638425579033A1***",
        "spaceId": "151481***",
        "sub": false,
        "resetFactory": false,
        "productId": "jv19g49qohpo8***",
        "uuid": "ca4ad1cb06be1***"
    },
    "ts": 1678951891665
}

Rename a device

Description of bizData

code	Data type	Description
devId	String	The device ID.
productId	String	The product ID of the specified device.
uid	String	The ID of the user who performs device pairing.
name	String	The name.
uuid	String	The universally unique identifier (UUID) of the specified device.

Example

{
    "bizCode": "deviceNameUpdate",
    "bizData": {
        "devId": "6c0946b2fff7b98d6em***",
        "uid": "ay1638425579033A1***",
        "productId": "jv19g49qohpo8***",
        "name": "Change name***",
        "uuid": "ca4ad1cb06be1***"
    },
    "ts": 1678952636853
}

OTA update (protocol 1002)

Device OTA update events

Description of bizData

code	Data type	Description
devId	String	The device ID.
progress	Integer	The update progress. Valid values: an integer between 0 and 100.
channel	String	The channel number. Valid values: `0`: Main module firmware. `1`: Bluetooth firmware. `3`: Zigbee firmware. `6`: Thread firmware. `9`: MCU firmware. `10` to `19`: Extended firmware.

Example

{
    "bizCode": "deviceOtaProgress",
    "bizData": {
        "devId": "6c622fa1f003b84e74i***",
        "progress": 100,
        "channel": 0
    },
    "ts": 1678703050654
}

Space (protocol 1010)

Create a space

Description of bizData

code Data type Description

spaceId String The ID of the specified space.

name String The name.

code	Data type	Description
spaceId	String	The ID of the specified space.
name	String	The name.

Example

{
    "bizCode": "spaceCreate",
    "bizData": {
        "spaceId": 152082***,
        "name": "Campus Space"
    },
    "ts": 1678691050625
}

Remove a space

Description of bizData

code Data type Description

spaceId String The ID of the specified space.

code	Data type	Description
spaceId	String	The ID of the specified space.

Example

{
    "bizCode": "spaceRemove",
    "bizData": {
        "spaceId": 152082***
    },
    "ts": 1678691097671
}

Rename a space

Description of bizData

code Data type Description

spaceId String The ID of the specified space.

name String The name.

code	Data type	Description
spaceId	String	The ID of the specified space.
name	String	The name.

Example

{
    "bizCode": "spaceUpdate",
    "bizData": {
        "spaceId": 152082***,
        "name": "Campus Space"
    },
    "ts": 1678691092910
}

Group (protocol 1020)

Create Group

Description of bizData

code	Data type	Description
groupId	Long	The ID of the specified group.
spaceId	String	The ID of the specified space.
name	String	The name.
time	Long	The 13-digit timestamp when the group was created.

Example

{
    "bizCode": "groupCreate",
    "bizData": {
        "spaceId": "151482***",
        "groupId": "12898***",
        "name": "Home Group",
        "time": 1678950226742
    },
    "ts": 1678950226751
}

Delete Group

Description of bizData

code Data type Description

groupId Long The ID of the specified group.

spaceId String The ID of the specified space.

time Long The 13-digit timestamp when the group was removed.

Example

{
    "bizCode": "groupDelete",
    "bizData": {
        "spaceId": "151482***",
        "groupId": "12898***",
        "time": "1678950436076"
    },
    "ts": 1678950436087
}

Modify a group

Description of bizData

code	Data type	Description
groupId	Long	The ID of the specified group.
spaceId	String	The ID of the specified space.
name	String	The name.
time	Long	The 13-digit timestamp when the group was modified.

Example

{
    "bizCode": "groupNameUpdate",
    "bizData": {
        "spaceId": "151482***",
        "groupId": "12898***",
        "name": "Home Group",
        "time": "1678950411961"
    },
    "ts": 1678950411998
}

Add devices to a group

Description of bizData

code	Data type	Description
groupId	Long	The ID of the specified group.
spaceId	String	The ID of the specified space.
devIds	List	Device list
time	Long	The 13-digit timestamp when devices were added to the group.

Example

{
    "bizCode": "groupDeviceAdd",
    "bizData": {
        "spaceId": "151482***",
        "groupId": "12898***",
        "devIds": [
            "vdevo167756814561***"
        ],
        "time": "1678950226762"
    },
    "ts": 1678950226775
}

Remove devices from a group

Description of bizData

code	Data type	Description
groupId	Long	The ID of the specified group.
spaceId	String	The ID of the specified space.
devIds	List	Device list
time	Long	The 13-digit timestamp when devices were removed from the group.

Example

{
    "bizCode": "groupDeviceRemove",
    "bizData": {
        "spaceId": "151482***",
        "groupId": "12898***",
        "devIds": [
            "vdevo166382916152***"
        ],
        "time": "1678950430449"
    },
    "ts": 1678950430462
}

Linkage rule (protocol 1030)

Modify a linkage rule

Description of bizData

code	Data type	Description
ruleId	Long	The ID of the specified rule.
eventCode	String	The code of the specified event. Valid values: `add`: Add a linkage rule. `modify`: Modify a linkage rule. `remove`: Remove a linkage rule. `disable`: Disable a linkage rule. `enable`: Enable a linkage rule. `state`: Change the operation type.
time	Long	The 13-digit timestamp when the linkage rule was changed.
eventData	EventData	The rule data. This parameter has a value when the value of `eventCode` is `state`.

Description of EventData

code	Data type	Description
runMode	String	The operation type. Valid values: `local`: local linkage. `lan`: linkage over LAN. `cloud`: linkage in the cloud.

Example

{
    "bizCode": "linkageRuleChangeComplete",
    "bizData": {
        "eventCode": "add",
        "time": 1678950742932,
        "ruleId": "t7sFRCpcMOjsv***"
    },
    "ts": 1678950744321
}

eventCode: state

Example

{
    "bizCode": "linkageRuleChangeComplete",
    "bizData": {
        "eventCode": "state",
        "eventData": {
            "runMode": "local"
        },
        "time": 1678950743000,
        "ruleId": "t7sFRCpcMOjsv***"
    },
    "ts": 1678950744509
}

Execute a linkage rule

Description of bizData

code	Data type	Description
eventId	String	The unique ID of the reported data. This ID has no business meaning.
ruleId	String	The ID of the specified rule.
spaceId	String	The ID of the specified space.
triggerEntityId	String	The ID of the specified user who triggers a rule.
startTime	Long	The 13-digit timestamp when the execution of a linkage rule started.
endTime	Long	The 13-digit timestamp when the execution of a linkage rule ended.
status	Long	The status of the execution. Valid values: `success`: The execution succeeded. `fail`: The execution failed. `noMatch`: The criteria do not match.

Example

{
    "bizCode": "linkageRuleExecuteComplete",
    "bizData": {
        "eventId": "6412c16547a0a2001f499***_t7sFRCpcMOjsv***",
        "spaceId": "151482***",
        "startTime": 1678950757833,
        "endTime": 1678950757874,
        "triggerEntityId": "bay1618908218427P***",
        "ruleId": "t7sFRCpcMOjsv***",
        "status": "success"
    },
    "ts": 1678950757902
}

Legacy version events

Report device data (protocol 4)

Report device status data

Special note for bizCode

The bizCode of this message is expected to be statusReport. Due to historical reasons, the bizCode field is not included in the final pushed message body. For specific push content, see the data example below. When consuming messages, use the protocol field in the outer layer of the message body for business processing. We apologize for the inconvenience caused.

Description of data

code	Data type	Description
dataId	String	The unique ID of the reported data. This ID has no business meaning.
devId	String	The device ID.
productKey	String	The product ID of the specified device.
status	List<StatusItem>	The list of the device status data reported this time.

Description of StatusItem

code	Data type	Description
code	String	The code of the specified device status reported.
value	Object	The status value of the code reported by the specified device.
t	Long	The 13-digit timestamp when the device status was reported.
“{dpId}”:“{dpValue}”	String:String	`dpId`: the code of the specified data point in the product definition. `dpValue`: the value of the specified data point.

Example

{
"dataId":"AAXI3c1i6xxx***",
"devId":"6c95a93fd9xxx***",
"productKey":"awgmk9pixxx***",
"status":[
    {
        "code":"switch_1",
        "value":false,
        "t":1628229842692,
        "1":"false"
    }
]
}

Manage device (protocol 20)

Go online

Description of bizData

code Data type Description

time Long The timestamp.

code	Data type	Description
time	Long	The timestamp.

Example

{
  "devId": "002dj00118fe34d9****",
  "productKey": "The product key defined on the Tuya Developer Platform",
  "bizCode": "online",
  "bizData": {
  "time": 146052438362
 }
}

Go offline

Description of bizData

code Data type Description

time Long The timestamp.

code	Data type	Description
time	Long	The timestamp.

Example

  {
    "devId": "002dj00118fe34d9****",
    "productKey": "The product key defined on the Tuya Developer Platform",
    "bizCode": "offline",
    "bizData": {
      "time": 146052438362
    }
  }

Rename a device

Description of bizData

code Data type Description

devId String The device ID.

name String The device name.

Example

{
  "devId": "002dj00118fe34d9****",
  "productKey": "The product key defined on the Tuya Developer Platform",
  "bizCode": "nameUpdate",
  "bizData": {
    "devId": "002dj00118fe34d9****",
    "name": "new name"
  }
}

Rename a data point

Description of bizData

code Data type Description

devId String The device ID.

name String The name of the specified data point.

dpId String The ID of the specified data point.

Example

{
  "devId": "002dj00118fe34d9****",
  "productKey": "The product key defined on the Tuya Developer Platform",
  "bizCode": "dpNameUpdate",
  "bizData": {
    "devId": "002dj00118fe34d9****",
    "name": "new name",
    "dpId": "dpId"
  }
}

Bind a device with a user account

Description of bizData

code	Data type	Description
devId	String	The device ID.
uuid	String	The universally unique identifier (UUID) of the specified device.
uid	String	The user ID bound with the device.
token	String	The token for device pairing.

Example

{
  "devId": "002dj00118fe34d9****",
  "productKey": "The product key defined on the Tuya Developer Platform",
  "bizCode": "bindUser",
  "bizData": {
    "devId": "002dj00118fe34d9****",
    "uuid": "06200043b4e618c1****",
    "uid":"ay1529485403390****",
    "token": "IIpQ****"
  }
}

Delete a device

Description of bizData

code Data type Description

devId String The device ID.

uid String The ID of the user that is bound with a device.

Example

{
  "devId": "002dj00118fe34d9****",
  "productKey": "The product key defined on the Tuya Developer Platform",
  "bizCode": "delete",
  "bizData": {
    "devId": "002dj00118fe34d9****",
    "uid":"ay1529485403390S****"
  }
}

Update the device status

Description of bizData

code	Data type	Description
devId	String	The device ID.
moduleType	Int	The module type. Valid values: `0`: Wi-Fi `1`: Bluetooth Low Energy (LE) `2`: GPRS
upgradeStatus	Int	The update status. Valid values: `1`: Prepare to update. `2`: An update is in progress. `3`: An update is completed. `4`: An exception occurs during an update process. `7`: An update timed out.
description	String	The description of an update.
oldVersion	String	The earlier firmware.
newVersion	String	The later firmware.

Example

{
    "bizCode":"upgradeStatus",
    "bizData": {
        "devId":"6ca8756d*****1b4ewsdn",
        "moduleType":0,
        "upgradeStatus":2,
        "description":"Update Test",
        "oldVersion": "1.0.1",
        "newVersion": "1.0.2"
    },
    "devId":"6ca8756d*****1b4ewsdn",
    "productKey":"vFHpaEFwu8UD****",
    "ts":1562232522192
}

IoT SIM card (protocol 43)

Suspend an IoT SIM card

Description of bizData

code	Data type	Description
iccid	String	The ID of the specified IoT SIM card.
deviceId	String	The device ID.
uid	String	The user ID.
pid	String	The product ID.
stopReason	String	Reasons for suspending the IoT SIM card. Valid values: `PACKAGE_EXHAUSTED`: The data is used up. `EXPIRE_PACKAGE`: The package has expired. `INVOKE:****`: It is called by the requesting party. `UNBIND_PACKAGE`: The package is unbound. `UNSUBSCRIBE_PACKAGE`: The package is unsubscribed.
reportTime	Long	The timestamp when data was reported.

Example

{
   "bizCode":"simStop",
   "bizData":{
    "iccid": "****",
    "deviceId": "****",
    "uid": "****",
    "pid": "****",
    "stopReason": "FLOW_OUT",
    "reportTime": 1620896040128
  },
 "ts":1625798044298
}

Send data usage alerts

Description of bizData

code	Data type	Description
iccid	String	The ID of the specified IoT SIM card.
deviceId	String	The device ID.
uid	String	The user ID.
pid	String	The product ID.
totalFlowAmount	String	The total available data amount.
usedFlowAmount	String	The amount of used data.
reportTime	Long	The timestamp when data was reported.

Example

{
   "bizCode":"simLimitAlarm",
   "bizData":{
    "iccid": "xxxx",
    "deviceId": "xxxx",
    "uid": "xxxx",
    "pid": "xxxx",
    "totalFlowAmount": 10240,
    "usedFlowAmount": 1024,
    "reportTime": 1620896040128
  },
 "ts":1625798044298
}

Third-party speaker (protocol 45)

Send voice prompts

Description of bizData

code Data type Description

brandCode String The brand code of the specified speaker.

voiceId String The device ID of the specified speaker.

command Array The command.
Description of command

code Data type Description

intent String The intention. For example, welcome can be used for showing welcome.

content Object The conent of a command.
Description of content

code Data type Description

value String The content for a voice prompt.

code	Data type	Description
brandCode	String	The brand code of the specified speaker.
voiceId	String	The device ID of the specified speaker.
command	Array	The command.

code	Data type	Description
intent	String	The intention. For example, `welcome` can be used for showing welcome.
content	Object	The conent of a command.

code	Data type	Description
value	String	The content for a voice prompt.

Example

{
    "bizCode":"textToSpeech",
    "bizData":{
        "brandCode":"abc*******",
        "voiceId":"def*******",
        "command": [{
            "intent": "welcome",
            "content":{
                "value": "Welcome to this hotel"
            }
        }]
    },
    "ts":1636682568127
}

Reset a third-party speaker

Message description

This message is sent when a third-party speaker is unbound or a guest checks out. On receiving the message, the voice platform will clear the usage history or the cache.
Description of bizData

code Data type Description

brandCode String The brand code of the specified speaker.

voiceId String The device ID of the specified speaker.

code	Data type	Description
brandCode	String	The brand code of the specified speaker.
voiceId	String	The device ID of the specified speaker.

Example

{
    "bizCode":"reset",
    "bizData":{
        "brandCode":"abc*******",
        "voiceId":"def*******"
    },
    "ts":1636682568127
}

Change custom Q&A data

Description of bizData

code Data type Description

spaceId String The ID of the specified space.

brandCodeList List The list of the speaker brand codes.

code	Data type	Description
spaceId	String	The ID of the specified space.
brandCodeList	List	The list of the speaker brand codes.

Example

{
    "bizCode":"customQAChange",
    "bizData":{
        "spaceId":"123*********",
        "brandCodeList":["abc*******","def*******"]
    },
    "ts":1636682568127
}

Automation (protocol 25)

Run an automation task

Description of bizData

code	Data type	Description
gid	Long	The linkage ID.
uid	String	The user ID.
id	String	The rule code.
name	String	The rule name.
ts	Long	The timestamp.
actions	List	The list of actions.

Description of Action

code	Data type	Description
id	String	The action ID.
execStatus	Integer	The execution status. Valid values: `-1`: default `0`: failure `1`: success `2`: to be executed `3`: no execution is required
entityId	String	The entity ID.
executeTime	Long	The 13-digit timestamp when the task was executed.

Example

{
    "bizCode":"automationExecute",
    "bizData":{
        "name": "If timer: 15:28 on June 20",
        "id":"SnKfREPRAA1V****",
        "actions":[
            {
                "entityId":"6c77824debdfd0ae55****",
                "execStatus":1,
                "executeTime":1687246080261,
                "id":"nAawbkQwgYn5iAgA****"
            }
        ]
    },
    "gid":4494****,
    "ts":1687246080541,
    "uid":"ay1638425579033A****"
}

Automate an external action (protocol 22)

Description of bizData

code Data type Description

automationId String The automation ID.

bizData JSON The custom data, to be used with POST/v1.0/homes/{home_id}/automations/{automation_id}/conditions/trigger.

code	Data type	Description
automationId	String	The automation ID.
bizData	JSON	The custom data, to be used with `POST/v1.0/homes/{home_id}/automations/{automation_id}/conditions/trigger`.

Example

{
    "automationId":"Rc5XAKLSmwpxH***",
    "bizCode":"automationExternalAction",
    "bizData":{
        "code":"mode",
        "value":2,
        "operator":"=="
    }
}

Scene (protocol 25)

Run a scene

Description of bizData

code	Data type	Description
name	String	The name of the specified scene.
id	String	The ID of the specified scene.
gid	Long	The home ID.
uid	String	The ID (UID) of the specified user who adds a scene.
ts	Long	The timestamp when a message was delivered.
actions.entityId	String	The entity ID.
actions.execStatus	Integer	The status of the action. Valid values: `-1`: default `0`: failure `1`: success `2`: to be executed `3`: no execution is required
actions.executeTime	Long	The timestamp when a scene was executed.
actions.id	String	The action ID.
actions.errorMsg	String	Error message

Example

{
   "bizData":{
    "name":"Switch-On",
    "id":"azmQ2w8kPSCdcr***",
    "actions":[
        {
            "entityId":"02167073cc****",
            "execStatus":1,
            "executeTime":1625798044277,
            "id":"1jPxz3zaNdL****"
        }
    ]
  },
 "gid":37081***,
 "uid":"ay1622715182388N****",
 "ts":1625798044298
}

Industrial assets (protocol 13001)

Bind a device with an industrial asset

Description of bizData

code	Data type	Description
devId	String	The device ID.
assetId	String	The asset ID.
uuid	String	The universally unique identifier (UUID) of the specified device.
token	String	The token for device pairing.

Example

{
    "bizCode":"industryAssetDeviceBind",
    "bizData":{
        "devId":"vdevo16872466190****",
        "assetId":"15845****",
        "uuid":"vdevo16872466190****",
        "token":""
    },
    "ts":1687246619772
}

Unbind a device from an industrial asset

Description of bizData

code Data type Description

devId String The device ID.

assetId String The asset ID.

uuid String The universally unique identifier (UUID) of the specified device.

Example

{
    "bizCode":"industryAssetDeviceUnbind",
    "bizData":{
        "devId":"vdevo16872466190****",
        "assetId":"15845****",
        "uuid":"vdevo16872466190****"
    },
    "ts":1687246961902
}

Change an industrial asset

Description of bizData

code	Data type	Description
assetId	String	The asset ID.
eventTime	String	The 13-digit timestamp when the event occurred.
assetName	String	The asset name.
eventType	String	The event type. Valid values: `add`: Add an asset. `update`: Rename an asset. `delete`: Remove an asset.

Example

{
    "bizCode":"industryAssetChange",
    "bizData":{
        "assetId":"15845****",
        "eventTime":1687247065523,
        "assetName":"my asset",
        "eventType":"add"
    },
    "ts":1687247065715
}

Infrared (protocol 50)

Unbind a device from an asset

Description of bizData

code	Data type	Description
devId	String	The device ID.
eventType	String	The event type. Valid values: `INFRARED_LEARN`: infrared learning.
learnCodeList	List<CodeItem>	The list of IR learning codes.

Description of CodeItem

code	Data type	Description
id	Long	The primary key of the specified learning code.
code	String	The learning code.
keyName	String	The description of the specified key.
name	String	The name of the specified key.

Example

{
    "bizCode":"infraredLearnMessage",
    "bizData":{
        "devId":"6c26d974ed10c1f894****",
        "eventType":"INFRARED_LEARN",
        "learnCodeList":{
            "id":4416011,
            "code":"015202f40172f401b****",
            "keyName":"Power Supply",
            "name":"power"
        }
    },
    "ts":1620896040128
}

Geofencing (protocol 40)

Geofencing alert

Description of bizData

code	Data type	Description
devId	String	The device ID.
tag	String	The dimension tag.
fenceId	Long	The ID of the specified geofence.
fenceName	String	The name of the specified geofence.
bindType	Integer	The binding type of the specified geofence. Valid values: `1`: private geofence. `2`: public geofence.
lat	Double	The latitude reported by the current device.
lon	Double	The longitude reported by the current device.
triggerType	String	The type of alert. Valid values: `1`: Enter the geofence. `2`: Exit the geofence.
reportTime	Long	The 13-digit timestamp when the data was reported.

Example

{
"bizCode":"outdoorsFenceAlarm",
"bizData":{
    "devId":"ay1617****",
    "tag":"*******",
    "fenceId":1000,
    "fenceName":"MyFence",
    "bindType":1,
    "lat":121.234,
    "lon":34.3478,
    "triggerType":"1",
    "reportTime":1620896040128
},
"ts":1620896040128
}

User event (protocol 54)

Register a user

Description of bizData

code	Data type	Description
uid	String	The user ID.
regFrom	Integer	The source of registration. Valid values: `0`: Register with an email address. `1`: Register with a mobile phone number. `2`: Register with other methods. `9`: Register with a third-party user ID (UID).
mobile	String	The mobile phone number.
nickname	String	The nickname.
phoneCode	String	The country code.
timezoneId	String	The ID of the specified time zone.
lang	String	The multilingual support.
gmtCreate	Long	The time when the user was created.
gmtModified	Long	The time when the user information was modified.
headPic	String	The URL of an avatar.
username	String	The username.
lastLoginTime	Long	The last login time.

Example

{
"bizCode": "userRegisterEvent",
"bizData": {
	"uid": "ay1695****e66",
	"regFrom": 9,
	"mobile": "",
	"nickname": "****",
	"phoneCode": "86",
	"timezoneId": "",
	"lang": "",
	"gmtCreate": 1695625445,
	"gmtModified": 1695710138,
	"headPic": "****",
	"username": "****",
	"lastLoginTime": 1695625445581
},
"ts": 1687246619772
}

Update a user

Description of bizData

code	Data type	Description
uid	String	The user ID.
regFrom	Integer	The source of registration. Valid values: `0`: Register with an email address. `1`: Register with a mobile phone number. `2`: Register with other methods. `9`: Register with a third-party user ID (UID).
mobile	String	The mobile phone number.
nickname	String	The nickname.
phoneCode	String	The country code.
timezoneId	String	The ID of the specified time zone.
lang	String	The multilingual support.
gmtCreate	Long	The time when the user was created.
gmtModified	Long	The time when the user information was modified.
headPic	String	The URL of an avatar.
username	String	The username.
lastLoginTime	Long	The last login time.

Example

  {
    "bizCode": "userUpdateEvent",
    "bizData": {
        "lastLoginTime": 1695625445581,
        "uid": "ay1695****e66",
        "regFrom": 9,
        "gmtModified": 1695710138,
        "mobile": "",
        "nickname": "****",
        "phoneCode": "86",
        "timezoneId": "",
        "lang": "",
        "gmtCreate": 1695625445,
        "headPic": "****",
        "username": "****"
    },
    "ts": 1687246619772
}

Delete a user

Description of bizData

code Data type Description

uid String The user ID.

Example

{
    "bizCode": "userDeleteEvent",
    "bizData": {
        "uid": "ay1695****e66"
    },
    "ts": 1687246619772
}

Home event (protocol 35)

Create a home

Description of bizData

code Data type Description

uid String The user ID.

homeId String The home ID.

homeName String The name of the specified home.

Example

{
    "bizCode": "homeCreate",
    "bizData": {
        "uid": "ay16957***0ZXwQ7",
        "homeName": "My Home***",
        "homeId": "***"
    },
    "ts": 1695712142936
}

Update a home

Description of bizData

code Data type Description

homeId String The home ID.

homeName String The name of the specified home.

lon Double The longitude.

lat Double The latitude.

Example

  {
  "bizCode": "homeUpdate",
  "bizData": {
  	"lon": xxxx,
  	"lat": xxxx,
  	"homeName": "My Home***",
  	"homeId": "***"
  },
  "ts": 1695712142936
 }

Delete a home

Description of bizData

code	Data type	Description
homeId	String	The home ID.
homeName	String	The name of the specified home.
memberIds	List<String>	The list of user IDs of home members.
devices	List<String>	The list of device IDs of the specified home.
reason	Integer	The reason why the specified home is deleted. Valid values: `1`: The specified user is deleted with the data cleared, so the home is dissolved and cleared. `2`: The specified user operates to dissolve the home, so the home is dissolved.

Example

{
    "bizCode": "homeDelete",
    "bizData": {
        "homeId": "***",
        "homeName": "My Home***",
        "memberIds": [],
        "devices":[],
        "reason": 1
    },
    "ts": 1695712142936
}

Invite a home member

Description of bizData

code	Data type	Description
homeId	String	The home ID.
operatorUid	String	The user ID of the specified inviter or operator.
memberUid	String	The user ID with the status changed.
eventType	String	The event type. Valid values: `agreeForMember`: The invitee accepts to join the home as a common member. `agreeForAdmin`: The invitee accepts to join the home as an administrator. `updateToMember`: The specified member role is modified to a common member role of the home. `updateToAdmin`: The specified member role is modified to an administrator role of the home. `inviteMember`: Invite a member.

Example

  {
    "bizCode": "homeMemberSharing",
    "bizData": {
        "homeId": "***",
        "operatorUid": "***",
        "memberUid": "***",
        "eventType": "agreeForMember"
    },
    "ts": 1687246619772
 }

Modify a home member

Description of bizData

code	Data type	Description
homeId	String	The home ID.
memberName	String	The name of the user with the status changed.
memberUid	String	The user ID with the status changed.
role	String	Modify the user to the specified role. Valid values: `member`: Common member `admin`: Administrator `owner`: Home owner

Example

 {
    "bizCode": "homeMemberUpdate",
    "bizData": {
        "homeId": "1746***",
        "memberName": "***",
        "memberUid": "***",
        "role": "member"
    },
    "ts": 1687246619772
}

Delete a home member

Description of bizData

code	Data type	Description
homeId	String	The home ID.
memberUid	String	The user ID with the status changed.
role	String	Modify the user to the specified role. Valid values: `member`: Common member `admin`: Administrator `owner`: Home owner
dealType	String	Specifies how to deal with the operation. Valid values: `declineInvitation`: Decline the invitation. `removed`: Delete the member.

Example

{
    "bizCode": "homeMemberDelete",
    "bizData": {
        "homeId": "1****2",
        "memberUid": "***",
        "role": "****",
        "dealType": "declineInvitation"
    },
    "ts": 1687246619772
}

Room event (protocol 34)

Create a room

Description of bizData

code Data type Description

uid String The user ID.

roomId Long The room ID.

roomName String The room name.

homeId String The home ID.

Example

{
    "bizCode": "roomCreate",
    "bizData": {
        "roomId": 12***,
        "roomName": "Bedroom",
        "homeId": "1**2**",
        "uid":"ay16957***0ZXwQ7"
    },
    "ts": 1687246619772
}

Create rooms in bulk

Description of bizData

code Data type Description

uid String The user ID.

homeId String The home ID.

rooms List<RoomVO> The list of rooms that are created.
Description of RoomVO

Code Data type Description

uid String The user ID.

roomId Long The room ID.

roomName String The room name.

homeId String The home ID.

Example

     {
      "bizCode": "roomBatchCreate",
      "bizData": {
          "homeId": "1***2",
          "uid": "ay16957***0ZXwQ7",
          "rooms": []
      },
      "ts": 1687246619772
   }

Delete a room

Description of bizData

code Data type Description

homeId String The home ID.

roomId Long The room ID.

Example


  {
    "bizCode": "roomDelete",
    "bizData": {
        "homeId": "xxx",
        "roomId": 12
    },
    "ts": 1687246619772
  }

Sort a room

Description of bizData

code Data type Description

homeId String The home ID.

rooms List<RoomVO> The list of rooms.
Description of RoomVO

code Data type Description

roomId Long The room ID.

order Integer The sorting value. The smaller the value, the higher order it is displayed.

Example

{
"bizCode": "roomSort",
"bizData": {
	"homeId": "xxx",
	"rooms": [{
		"roomId": 21,
		"order": 1
	}, {
		"roomId": 11,
		"order": 2

	}]
},
"ts": 1687246619772
}

Rename a room

Description of bizData

code Data type Description

homeId String The home ID.

roomId Long The room ID.

roomName String The room name.

Example

  {
    "bizCode": "roomNameUpdate",
    "bizData": {
        "homeId": "xxx",
        "roomId": 12xx,
        "roomName": "Bedroom"
    },
    "ts": 1687246619772
  }

Prev DocData Signature and Decryption

Next DocBest Practices

code	Data type	Description
uid	String	The user ID.
roomId	Long	The room ID.
roomName	String	The room name.
homeId	String	The home ID.