Smart Scenes

Last Updated on : 2026-01-22 09:24:07download

Smart scenes include two types: tap-to-run and automation.

Tap-to-run: Users can add actions to a tap-to-run scene. Later, they can tap the scene to run it when needed.
Automation: Users can set specific conditions to run a smart scene. When the conditions are met, the specified action is automatically triggered.

Functional description

Tuya supports users’ smart life requirements. For example, set weather conditions or device status as triggers for a specific smart scene. When any triggers occur, one or more linked devices will run predefined tasks.

Class name	Description
TSmartScene	Provides operations to query, run, delete, and enable/disable scenes, using static method calls.
NormalSceneBean	The data model for a scene, containing its basic information, condition list, and action list.
SceneCondition	The data model for a scene condition, representing the trigger condition of a scene.
SceneAction	The data model for a scene action, representing the task executed by a scene.

Before you make API requests for smart scenes, learn about scene conditions and scene tasks.

Scene conditions

The SceneCondition class is used to manage scene conditions. Tuya supports the following conditions:

Weather conditions: Temperature, humidity, weather, PM2.5, air quality, sunrise, and sunset. Users can select the current city when they set weather conditions.
Device conditions: Users can predefine a device condition in a specific smart scene. When this condition is met, the task in the specified smart scene will be triggered. The same device cannot be used as a condition and a task at the same time. Otherwise, operational conflicts might occur.
Schedule: An action can be scheduled to run at a specific time.

SceneCondition object:

Parameter	Type	Description
entityName	String	The condition name.
entityId	String	The device ID. This field works for device conditions.
entityType	Int	The type of condition. Example: Tap-to-run: `99` Device: `1` Weather condition: `3` Schedule: `6` PIR: `7` Geofence: `10` When home members come home: `11` Security: `12` Duration calculation: `13` Sunset and sunrise: `16` Energy: `28` Struct: `30`
entitySubIds	String	The identifiers of the conditions other than devices. Example: Temperature: `temp` Humidity: `humidity` Weather condition: `condition` PM2.5: `pm25` Air quality index: `aqi` Sunrise and sunset: `sunsetrise` Wind speed: `windSpeed`

Scene tasks

In a scene task, one or more devices are triggered to run specific tasks when specified weather or device conditions are met in the scene. The SceneAction class is used to manage scene tasks, disable or enable an automation scene.

SceneAction object:

Field	Type	Description
actionId	String	The action ID.
entityId	String	The device ID.
entityName	String	The device name.
actionExecutor	String	The type of the action. Enum values: `ruleTrigger`: Trigger a scene. `ruleEnable`: Enable a scene. `ruleDisable`: Disable a scene. `appPushTrigger`: Push a notification. `mobileVoiceSend`: Make a phone call. `smsSend`: Send an SMS message. `deviceGroupDpIssue`: Control a device group. `irIssue`: Control an IR device. `dpIssue`: Control a common device. `delay`: Delay an action. `irIssueVii`: Control an IR device with real IR codes. `toggle`: Run an on/off action. `dpStep`: Run a step action.
executorProperty	Dictionary	The execution details of an action.
extraProperty	Dictionary	The additional information about an action.

Query scenes

Query the lightweight list of scenes

API description

Tap-to-run and automation scenes are queried in the same request. The conditions field can be set or not to differentiate between the two types of smart scenes. This API method is a lightweight version of querying the complete list of scenes.

static getSimpleSceneAll(relationId: number): Promise<TSmartAtopResponse<NormalSceneBean[]>>

Parameters

Parameter	Type	Description
relationId	number	The ID of the specified home.

Return values

Returns Promise<TSmartAtopResponse<NormalSceneBean[]>>, where the result field contains an array of scene objects.

Sample code

TSmartScene.getSimpleSceneAll(this.currentHomeId).then((data) => {
  if (data.result) {
    this.sceneList = data.result
    // Handle the scene list
  }
}).catch((error: Error) => {
  console.error('Failed to load scene list:', error)
})

Query a list of scenes by linkage type

API description

Query a list of scenes based on the linkage type. This API method is currently used in the tap-to-run list on the device homepage.

static getHomeSceneListByType(
  relationId: number,
  sceneType: number,
  page: number | undefined,
  pageSize: number | undefined
): Promise<TSmartAtopResponse<FusionPageNormalScenes>>

Parameters

Parameter	Type	Description
relationId	number	The relation (home) ID.
sceneType	number	The scene type: `1`: Tap-to-run `2`: Automation
page	number	The page number (optional).
pageSize	number	The number of items returned per page (optional).

Return values

Returns Promise<TSmartAtopResponse<FusionPageNormalScenes>>, including a list of scenes on pages.

Sample code

TSmartScene.getHomeSceneListByType(currentHomeId, 1, undefined, undefined).then((data)=> {
  if (data.result) {
    this.sceneList = data.result.datas
    // Handle the scene list
  }
}).catch((error: Error) => {
  console.error('Failed to load scene list:', error)
})

Query scene details

API description

Query detailed information of a scene based on its scene ID, including complete information such as the condition list and action list.

static getSceneDetailV1(
  relationId: number,
  sceneId: string,
  ruleGenre?: number,
  homeModel?: boolean
): Promise<TSmartAtopResponse<NormalSceneBean>>

Parameters

Parameter	Type	Description
homeId	number	The ID of the specified home.
sceneId	string	The scene ID.
ruleGenre	number	The scene type (optional). `1`: Tap-to-run `2`: Automation
homeModel	boolean	Indicates support for room information (optional). If this field is set to `true`, the room associated with the scene will be returned. If this field is set to `false`, the room associated with the scene will not be returned.

Return values

Returns Promise<TSmartAtopResponse<NormalSceneBean>>, where the result field contains the scene details object.

NormalSceneBean object

Parameter	Type	Description
id	String	The scene ID.
name	String	The scene name.
enabled	Bool	Indicates whether an automation scene is enabled.
conditions	Array	The list of scene conditions, that is, a collection of `SceneCondition` objects.
actions	Array	The list of scene actions, that is, a collection of `SceneAction` objects.
coverIcon	String	The icon of the tap-to-run scene.
displayColor	String	The background color of the scene.
outOfWork	Int	The state of a scene. `0`: Normal `1`: Invalid `2`: Anomaly
ruleGenre	Int	The scene type: `1`: Tap-to-run `2`: Automation

Sample code

const currentHomeId = TSmartHomeManager.getInstance().getCurrentHomeId() ?? 0
TSmartScene.getSceneDetailV1(currentHomeId, this.sceneId, undefined, true).then((response) => {
  if (response && response.result) {
    this.sceneDetail = response.result
  }
}).catch((error: Error) => {
  console.error('Failed to load scene details:', error)
})

Scene operations

Save a scene

API description

Create a scene.

static saveScene(
  relationId: number,
  sceneData: NormalSceneBean
): Promise<TSmartAtopResponse<NormalSceneBean>>

Parameters

Parameter	Type	Description
relationId	number	The relation (home) ID.
sceneData	NormalSceneBean	The data model of the scene.

Return values

Returns Promise<TSmartAtopResponse<NormalSceneBean>>, containing the created scene information.

Sample code

const currentHomeId = TSmartHomeManager.getInstance().getCurrentHomeId() ?? 0
const sceneData: NormalSceneBean = {
  name: 'New Scene',
  ruleGenre: 1,
  actions: []
  // ... Other fields
}
TSmartScene.saveScene(currentHomeId, sceneData).then((result) => {
  if (result && result.result) {
    console.info('Scene saved successfully:', result.result)
  }
}).catch((error: Error) => {
  console.error('Failed to save the scene:', error)
})

(New) Save a scene

API description

This new API for saving a scene will only return the scene ID and scene name.

static saveRule(
  gid: number,
  sceneData: NormalSceneBean
): Promise<TSmartAtopResponse<NormalSceneBean>>

Parameters

Parameter	Type	Description
gid	number	The ID of the specified home.
sceneData	NormalSceneBean	The data model of the scene.

Return values

Returns Promise<TSmartAtopResponse<NormalSceneBean>>, only containing the scene ID and name.

Sample code

const currentHomeId = TSmartHomeManager.getInstance().getCurrentHomeId() ?? 0
const sceneData: NormalSceneBean = {
  name: 'New Scene',
  ruleGenre: 1,
  actions: []
  // ... Other fields
}
TSmartScene.saveRule(currentHomeId, sceneData).then((result) => {
  if (result && result.result) {
    console.info('Scene saved successfully:', result.result)
  }
}).catch((error: Error) => {
  console.error('Failed to save the scene:', error)
})

Edit a scene

API description

Modify an existing scene.

static modifyScene(
  sceneId: string,
  sceneData: NormalSceneBean,
  needCleanGidSid: boolean | undefined
): Promise<TSmartAtopResponse<NormalSceneBean>>

Parameters

Parameter	Type	Description
sceneId	string	The scene ID.
sceneData	NormalSceneBean	The data model of the scene.
needCleanGidSid	boolean	Indicates whether GID and SID need to be cleaned up (optional).

Return values

Returns Promise<TSmartAtopResponse<NormalSceneBean>>, containing the modified scene information.

Sample code

const sceneData: NormalSceneBean = {
  name: 'Modified Scene',
  ruleGenre: 1,
  actions: []
  // ... Other fields
}
TSmartScene.modifyScene(this.sceneId, sceneData, undefined).then((result) => {
  if (result && result.result) {
    console.info('Scene edited successfully:', result.result)
  }
}).catch((error: Error) => {
  console.error('Failed to edit the scene:', error)
})

Run a scene

API description

Run a tap-to-run scene and trigger all the actions defined within that scene.

This API method is only used to send commands to the cloud for running smart scenes. To check whether the target device has finished the required tasks, you canlisten for the DP status changes of the device.

static executeScene(sceneId: string): Promise<TSmartAtopResponse<boolean>>

Parameters

Parameter	Type	Description
sceneId	string	The scene ID.

Return values

Returns Promise<TSmartAtopResponse<boolean>>. The result field being true indicates successful execution, and false indicates failure.

Sample code

executeScene() {
  TSmartScene.executeScene(this.sceneId).then((result) => {
    if (result && result.result) {
      console.info('Scene run successfully:')
    }
  }).catch((error: Error) => {
    console.error('Failed to run the scene:', error)
  })
}

Delete a scene

API description

Delete the specified tap-to-run or automation scene.

static deleteSceneWithHomeId(homeId: number, sceneId: string): Promise<TSmartAtopResponse<boolean>>

Parameters

Parameter	Type	Description
homeId	number	The ID of the specified home.
sceneId	string	The scene ID.

Return values

Returns Promise<TSmartAtopResponse<boolean>>. The result field being true indicates successful deletion, and false indicates failure.

Sample code

deleteScene() {
  const currentHomeId = TSmartHomeManager.getInstance().getCurrentHomeId() ?? 0
  TSmartScene.deleteSceneWithHomeId(currentHomeId, this.sceneId).then((result) => {
    if (result && result.result) {
      console.info('Scene deleted successfully')
    }
  }).catch((error: Error) => {
    const errorMessage = error instanceof Error ? error.message : String(error)
    console.error('Failed to delete the scene:', errorMessage)
  })
}

Bulk delete smart scenes

API description

Delete smart scenes in bulk, with multiple scene IDs separated by a comma (,).

static deleteBatchSceneData(homeId: number, ruleIds: string): Promise<TSmartAtopResponse<boolean>>

Parameters

Parameter	Type	Description
homeId	number	The ID of the specified home.
ruleIds	string	The list of scene IDs, with multiple IDs separated by a comma (,). For example, `"sceneId1,sceneId2"`.

Return values

Returns Promise<TSmartAtopResponse<boolean>>. The result field being true indicates successful deletion.

Sample code

deleteSceneList() {
  const currentHomeId = TSmartHomeManager.getInstance().getCurrentHomeId() ?? 0
  TSmartScene.deleteBatchSceneData(currentHomeId, this.sceneIdList).then((result) => {
    if (result && result.result) {
      console.info('Scenes were deleted in bulk')
    }
  }).catch((error: Error) => {
    const errorMessage = error instanceof Error ? error.message : String(error)
    console.error('Failed to delete scenes in bulk', errorMessage)
  })
}

Enable an automation scene

Only automation scenes can be enabled or disabled.

API description

Enable an automation scene so that it runs automatically when the conditions are met.

static enableAutomation(sceneId: string): Promise<TSmartAtopResponse<boolean>>

Parameters

Parameter	Type	Description
sceneId	string	The scene ID.

Return values

Returns Promise<TSmartAtopResponse<boolean>>. The result field being true indicates a scene was enabled successfully, and false indicates failure to enable the scene.

Sample code

TSmartScene.enableAutomation(this.sceneId).then((response) => {
  if (response.result) {
    console.info('Scene enabled successfully')
  }
}).catch((error: Error) => {
  console.error('Failed to enable the scene:', error)
})

Disable an automation scene

API description

Disable an automation scene to prevent it from running automatically.

static disableAutomation(sceneId: string): Promise<TSmartAtopResponse<boolean>>

Parameters

Parameter	Type	Description
sceneId	string	The scene ID.

Return values

Returns Promise<TSmartAtopResponse<boolean>>. The result field being true indicates a scene was disabled successfully, and false indicates failure to disable the scene.

Sample code

TSmartScene.disableAutomation(this.sceneId).then((response) => {
  if (response.result) {
    console.info('Scene disabled successfully')
  }
}).catch((error: Error) => {
  console.error('Failed to disable the scene:', error)
})

Bulk modify rooms for a scene

API description

Modify rooms for a scene in bulk.

static batchModifySceneRooms(
  relationId: number,
  ruleIds: string,
  roomIds: string
): Promise<TSmartAtopResponse<boolean>>

Parameters

Parameter	Type	Description
relationId	number	The relation (home) ID.
ruleIds	string	The list of scene IDs, separated with commas (,).
roomIds	string	The list of room IDs, separated with commas (,).

Return values

Returns Promise<TSmartAtopResponse<boolean>>. The result field being true indicates rooms were modified successfully.

Sample code

const currentHomeId = TSmartHomeManager.getInstance().getCurrentHomeId() ?? 0
TSmartScene.batchModifySceneRooms(currentHomeId, 'sceneId1,sceneId2', 'roomId1,roomId2').then((result) => {
  if (result && result.result) {
    console.info('Room assignment for the scenes successfully modified in bulk')
  }
}).catch((error: Error) => {
  console.error('Failed to modify the room assignment for the scenes in bulk:', error)
})

Sort scenes

API description

Sort the existing scenes.

static sortSceneList(relationId: number, sceneIds: string[]): Promise<TSmartAtopResponse<boolean>>

Parameters

Parameter	Type	Description
relationId	number	The relation (home) ID.
sceneIds	string[]	The list of sorted smart scenes.

Return values

Returns Promise<TSmartAtopResponse<boolean>>. The result field being true indicates scenes were sorted successfully.

Sample code

const currentHomeId = TSmartHomeManager.getInstance().getCurrentHomeId() ?? 0
TSmartScene.sortSceneList(currentHomeId, ['sceneId1', 'sceneId2', 'sceneId3']).then((result) => {
  if (result && result.result) {
    console.info('Scene list sorted successfully')
  }
}).catch((error: Error) => {
  console.error('Failed to sort the scene list:', error)
})

Scene conditions and actions

Get a list of conditions

API description

Get a list of scene conditions, including weatherconditions and device conditions.

static getConditionAll(
  relationId: number,
  showFahrenheit: boolean,
  windSpeedUnit: string | undefined
): Promise<ConditionItemList>

Parameters

Parameter	Type	Description
relationId	number	The relation (home) ID.
showFahrenheit	boolean	Indicates whether the temperature is displayed in Fahrenheit.
windSpeedUnit	string	The unit of wind speed (optional).

Return values

Returns Promise<ConditionItemList>, containing a list of conditions categorized by environmental conditions, device conditions, and security conditions.

Sample code

const currentHomeId = TSmartHomeManager.getInstance().getCurrentHomeId() ?? 0
TSmartScene.getConditionAll(currentHomeId, false, undefined).then((data) => {
  console.info('The list of conditions obtained successfully', data)
}).catch((error: Error) => {
  console.error('Failed to get the list of conditions:', error)
})

Get a list of extended conditions (v2)

API description

Get a list of extended conditions.

static getExtendConditionsV2(
  relationId: number,
  appVersion: string
): Promise<TSmartAtopResponse<ExtendItem[]>>

Parameters

Parameter	Type	Description
relationId	number	The relation (home) ID.
appVersion	string	The app version number. For example, `"5.16.0"`.

Return values

Returns Promise<TSmartAtopResponse<ExtendItem[]>>, containing a list of extended conditions.

Sample code

const currentHomeId = TSmartHomeManager.getInstance().getCurrentHomeId() ?? 0
TSmartScene.getExtendConditionsV2(currentHomeId, '5.16.0').then((result) => {
  if (result && result.result) {
    console.info('The list of extended conditions obtained successfully', result.result)
  }
}).catch((error: Error) => {
  console.error('Failed to get the list of extended conditions:', error)
})

Get a list of extended actions

API description

Get a list of extended actions.

static getExtendActions(relationId: number): Promise<TSmartAtopResponse<ExtendItem[]>>

Parameters

Parameter	Description
relationId	The relation (home) ID.

Return values

Returns Promise<TSmartAtopResponse<ExtendItem[]>>, containing a list of extended actions.

Sample code

const currentHomeId = TSmartHomeManager.getInstance().getCurrentHomeId() ?? 0
TSmartScene.getExtendActions(currentHomeId).then((result) => {
  if (result && result.result) {
    console.info('The list of extended actions obtained successfully', result.result)
  }
}).catch((error: Error) => {
  console.error('Failed to get the list of extended actions:', error)
})

Get a list of extended actions (v2)

API description

Get a list of extended actions. This version of the interface returns the Space Snapshot actions by default, which can be displayed or hidden as needed.

static getExtendActionsV2(gid: number, appVersion: string): Promise<TSmartAtopResponse<ExtendItem[]>>

Parameters

Parameter	Type	Description
gid	number	The ID of the specified home.
appVersion	string	The app version number. For example, `"1.0.0"`.

Return values

Returns Promise<TSmartAtopResponse<ExtendItem[]>>, containing a list of extended actions.

Sample code

const currentHomeId = TSmartHomeManager.getInstance().getCurrentHomeId() ?? 0
TSmartScene.getExtendActionsV2(currentHomeId, '1.0.0').then((result) => {
  if (result && result.result) {
    console.info('The list of extended actions obtained successfully', result.result)
  }
}).catch((error: Error) => {
  console.error('Failed to get the list of extended actions:', error)
})

Scene logs

Get scene running logs

API description

Get scene running logs, including local logs.

static getSceneLogInfoAll(
  relationId: number,
  startTime: number,
  endTime: number,
  size: number,
  lastId: string | undefined,
  logSources: string | undefined,
  lastRecordTime: number | undefined
): Promise<TSmartAtopResponse<ExecuteLogList>>

Parameters

Parameter	Type	Description
relationId	number	The relation (home) ID.
startTime	number	The start time (timestamp, in milliseconds).
endTime	number	The end time (timestamp, in milliseconds).
size	number	The number of items returned per page.
lastId	string	The ID of the last log entry obtained in the previous request (optional, used for pagination).
logSources	string	The log source (optional).
lastRecordTime	number	The time of the last log entry obtained in the previous request (optional, used for pagination).

Return values

Returns Promise<TSmartAtopResponse<ExecuteLogList>>, containing the log list and total number.

Sample code

const currentHomeId = TSmartHomeManager.getInstance().getCurrentHomeId() ?? 0
const startTime = Date.now() - 7 * 24 * 60 * 60 * 1000 // 7 days ago
const endTime = Date.now() // Current time
TSmartScene.getSceneLogInfoAll(currentHomeId, startTime, endTime, 20, undefined, undefined, undefined).then((result) => {
  if (result && result.result) {
    console.info('Scene running logs obtained successfully:', result.result)
  }
}).catch((error: Error) => {
  console.error('Failed to get the scene running logs', error)
})

Get the details of scene running logs

API description

Get the details of scene running logs.

static getExecuteLogDetail(
  relationId: number,
  eventId: string | undefined,
  startTime: number,
  endTime: number,
  returnType: number
): Promise<TSmartAtopResponse<ExecuteLogDetail[]>>

Parameters

Parameter	Type	Description
relationId	number	The relation (home) ID.
eventId	string	The event ID (optional).
startTime	number	The start time (timestamp, in milliseconds).
endTime	number	The end time (timestamp, in milliseconds).
returnType	number	The return type. `1`: Retrieve all logs. `0`: Retrieve error logs only.

Return values

Returns Promise<TSmartAtopResponse<ExecuteLogDetail[]>>, containing the list of log details.

Sample code

const currentHomeId = TSmartHomeManager.getInstance().getCurrentHomeId() ?? 0
const startTime = Date.now() - 7 * 24 * 60 * 60 * 1000 // 7 days ago
const endTime = Date.now() // Current time
TSmartScene.getExecuteLogDetail(currentHomeId, undefined, startTime, endTime, 1).then((result) => {
  if (result && result.result) {
    console.info('Details of scene running logs obtained successfully:', result.result)
  }
}).catch((error: Error) => {
  console.error('Failed to get the details of scene running logs', error)
})

Check for new scene logs

API description

Check for new scene logs in the current home.

static hasNewlyGeneratedSceneLog(relationId: number): Promise<TSmartAtopResponse<boolean>>

Parameters

Parameter	Type	Description
relationId	number	The relation (home) ID.

Return values

Returns Promise<TSmartAtopResponse<boolean>>. The result field being true indicates that there are new logs, and false indicates that there are no new logs.

Sample code

const currentHomeId = TSmartHomeManager.getInstance().getCurrentHomeId() ?? 0
TSmartScene.hasNewlyGeneratedSceneLog(currentHomeId).then((result) => {
  if (result && result.result) {
    console.info('New scene log generated')
  } else {
    console.info('No new scene log generated')
  }
}).catch((error: Error) => {
  console.error('Failed to check scene logs:', error)
})

Recommended scenes

Get a list of recommended scenes

API description

Get a list of recommended scenes.

static getUnifiedRecommendAll(
  relationId: number,
  source: string,
  size: number,
  withAdded: boolean,
  devId: string | undefined,
  recommendSource?: string
): Promise<TSmartAtopResponse<RecommendScene[]>>

Parameters

Parameter	Type	Description
relationId	number	The relation (home) ID.
source	string	The source. `TAB`: The smart tab. `HOME_TOP`: The top of the homepage. `DEVICE_BIND`: Device pairing.
size	number	The number of recommended scenes.
withAdded	boolean	Indicates whether to show the recommended scene that has been added.
devId	string	The device ID (optional). It is required after the device is paired.
recommendSource	string	The recommendation type (optional).

Return values

Returns Promise<TSmartAtopResponse<RecommendScene[]>>, containing a list of recommended scenes.

Sample code

const currentHomeId = TSmartHomeManager.getInstance().getCurrentHomeId() ?? 0
TSmartScene.getUnifiedRecommendAll(currentHomeId, 'TAB', 10, false, undefined, undefined).then((result) => {
  if (result && result.result) {
    console.info('The list of recommended scenes obtained successfully:', result.result)
  }
}).catch((error: Error) => {
  console.error('Failed to get the list of recommended scenes:', error)
})

Get details of a recommended scene

API description

Get the details of a recommended scene.

static requestRecommendDetail(
  relationId: number,
  sceneId: string
): Promise<TSmartAtopResponse<RecommendScene>>

Parameters

Parameter	Type	Description
relationId	number	The relation (home) ID.
sceneId	string	The ID of the recommended scene.

Return values

Returns Promise<TSmartAtopResponse<RecommendScene>>, containing the details of the recommended scene.

Sample code

const currentHomeId = TSmartHomeManager.getInstance().getCurrentHomeId() ?? 0
TSmartScene.requestRecommendDetail(currentHomeId, this.recommendSceneId).then((result) => {
  if (result && result.result) {
    console.info('The details of recommended scenes obtained successfully:', result.result)
  }
}).catch((error: Error) => {
  console.error('Failed to get the details of recommended scenes:', error)
})

Get scenes recommended on the homepage

API description

Get a list of scenes recommended on the homepage.

static getHomeRecommend(relationId: number): Promise<TSmartAtopResponse<RecommendScene[]>>

Parameters

Parameter	Type	Description
relationId	number	The relation (home) ID.

Return values

Returns Promise<TSmartAtopResponse<RecommendScene[]>>, containing a list of scenes recommended on the homepage.

Sample code

const currentHomeId = TSmartHomeManager.getInstance().getCurrentHomeId() ?? 0
TSmartScene.getHomeRecommend(currentHomeId).then((result) => {
  if (result && result.result) {
    console.info('Recommended scenes for the homepage obtained successfully:', result.result)
  }
}).catch((error: Error) => {
  console.error('Failed to get recommended scenes for the homepage:', error)
})

Remove pinned recommended scenes from homepage

API description

Remove the pinned recommended scenes from the homepage.

static removeHomeRecommend(gid: number, recommendId: string): Promise<TSmartAtopResponse<boolean>>

Parameters

Parameter	Type	Description
gid	number	The ID of the specified home.
recommendId	string	The ID of the recommended scene template.

Return values

Returns Promise<TSmartAtopResponse<boolean>>. The result field being true indicates a scene was removed successfully.

Sample code

const currentHomeId = TSmartHomeManager.getInstance().getCurrentHomeId() ?? 0
TSmartScene.removeHomeRecommend(currentHomeId, this.recommendId).then((result) => {
  if (result && result.result) {
    console.info('The pinned recommended scene removed from the homepage successfully')
  }
}).catch((error: Error) => {
  console.error('Failed to remove the pinned recommended scene from the homepage:', error)
})

Add a recommended scene

API description

Add a recommended scene to a home.

static addRecommend(
  gid: number,
  recommendId: string,
  ruleExpr: RecommendScene
): Promise<TSmartAtopResponse<RecommendScene>>

Parameters

Parameter	Type	Description
gid	number	The ID of the specified home.
recommendId	string	The ID of the recommended scene.
ruleExpr	RecommendScene	The data model for the entire recommended scene.

Return values

Returns Promise<TSmartAtopResponse<RecommendScene>>, containing the data of the added recommended scene.

Sample code

const currentHomeId = TSmartHomeManager.getInstance().getCurrentHomeId() ?? 0
const recommendScene: RecommendScene = {
  // ... Recommended scene data
}
TSmartScene.addRecommend(currentHomeId, this.recommendId, recommendScene).then((result) => {
  if (result && result.result) {
    console.info('Recommended scene added successfully:', result.result)
  }
}).catch((error: Error) => {
  console.error('Failed to add recommended scene:', error)
})

Remove disliked recommended scene

API description

Remove a disliked recommended scene.

static removeRecommend(
  gid: number,
  recommendId: string,
  recommendSource: string
): Promise<TSmartAtopResponse<boolean>>

Parameters

Parameter	Type	Description
gid	number	The ID of the specified home.
recommendId	string	The ID of the recommended scene.
recommendSource	string	The source of the recommendation. `1`: linkage `2`: energy `3`: warning

Return values

Returns Promise<TSmartAtopResponse<boolean>>. The result field being true indicates a scene was removed successfully.

Sample code

const currentHomeId = TSmartHomeManager.getInstance().getCurrentHomeId() ?? 0
TSmartScene.removeRecommend(currentHomeId, this.recommendId, '1').then((result) => {
  if (result && result.result) {
    console.info('The disliked recommended scene successfully removed')
  }
}).catch((error: Error) => {
  console.error('Failed to remove disliked recommended scene:', error)
})

Get recommended scenes by device ID

API description

Get the list of recommended scenes by device ID.

static getRecommendListForDeviceIDs(
  deviceIDs: string,
  gid: number
): Promise<TSmartAtopResponse<RecommendScene[]>>

Parameters

Parameter	Type	Description
deviceIDs	string	The string of device IDs, separated with commas (,).
gid	number	The ID of the specified home.

Return values

Returns Promise<TSmartAtopResponse<RecommendScene[]>>, containing a list of recommended scenes corresponding to the device.

Sample code

const currentHomeId = TSmartHomeManager.getInstance().getCurrentHomeId() ?? 0
TSmartScene.getRecommendListForDeviceIDs('deviceId1,deviceId2', currentHomeId).then((result) => {
  if (result && result.result) {
    console.info('The list of recommended scenes successfully obtained based on the device ID:', result.result)
  }
}).catch((error: Error) => {
  console.error('Failed to get the list of recommended scenes based on the device ID:', error)
})

AI recommended scenes

AI-based scene recommendations for devices

API description

Get a list of AI-recommended scenes based on devices. Basic information of scene templates is returned.

static getAIRecommendListForDeviceIDs(
  gid: number,
  devIds: string,
  limitCount?: number
): Promise<TSmartAtopResponse<RecommendScene[]>>

Parameters

Parameter	Type	Description
gid	number	The ID of the specified home.
devIds	string	The device IDs, separated with commas (,). For example, `'dsih12e1,3rfsawd2'`.
limitCount	number	The limit count (optional).

Return values

Returns Promise<TSmartAtopResponse<RecommendScene[]>>, containing a list of AI recommended scenes corresponding to the device.

Sample code

const currentHomeId = TSmartHomeManager.getInstance().getCurrentHomeId() ?? 0
TSmartScene.getAIRecommendListForDeviceIDs(currentHomeId, 'deviceId1,deviceId2', 10).then((result) => {
  if (result && result.result) {
    console.info('The recommended list was successfully generated based on device AI scenes:', result.result)
  }
}).catch((error: Error) => {
  console.error('Failed to generate the recommended list based on device AI scenes:', error)
})

Add an AI-recommended scene

API description

Add an AI-recommended scene.

static addAIRecommend(
  gid: number,
  devId: string,
  templateId: string
): Promise<TSmartAtopResponse<boolean>>

Parameters

Parameter	Type	Description
gid	number	The ID of the specified home.
devId	string	The device ID.
templateId	string	The ID of a specified template.

Return values

Returns Promise<TSmartAtopResponse<boolean>>. The result field being true indicates scenes were added successfully.

Sample code

const currentHomeId = TSmartHomeManager.getInstance().getCurrentHomeId() ?? 0
TSmartScene.addAIRecommend(currentHomeId, this.deviceId, this.templateId).then((result) => {
  if (result && result.result) {
    console.info('AI recommended scene added successfully')
  }
}).catch((error: Error) => {
  console.error('Failed to add AI recommended scene:', error)
})

Add AI recommended scenes in bulk

API description

Add AI recommended scenes in bulk.

static batchAddAIRecommends(
  gid: number,
  devId: string,
  templateIds: string
): Promise<TSmartAtopResponse<boolean>>

Parameters

Parameter	Type	Description
gid	number	The ID of the specified home.
devId	string	The device ID.
templateIds	string	The template IDs, separated with commas (,). For example, `'7ds23fds,324fdsg9'`.

Return values

Returns Promise<TSmartAtopResponse<boolean>>. The result field being true indicates scenes were added successfully.

Sample code

const currentHomeId = TSmartHomeManager.getInstance().getCurrentHomeId() ?? 0
TSmartScene.batchAddAIRecommends(currentHomeId, this.deviceId, 'templateId1,templateId2').then((result) => {
  if (result && result.result) {
    console.info('AI recommended scenes added successfully in bulk')
  }
}).catch((error: Error) => {
  console.error('Failed to add AI recommended scenes in bulk:', error)
})

Delayed task

Get a list of delayed tasks

API description

Query a list of delayed tasks for a specified scene.

static getRuleDelayList(
  gid: number,
  startTime: string,
  endTime: string,
  timeZoneId: string,
  limit: number
): Promise<TSmartAtopResponse<DelayItem[]>>

Parameters

Parameter	Type	Description
gid	number	The ID of the specified home.
startTime	string	The start time, current timestamp, in milliseconds.
endTime	string	The end time, a timestamp 30 days after the current time, in milliseconds.
timeZoneId	string	The time zone ID. For example, `'Asia/Shanghai'`.
limit	number	The limit count.

Return values

Returns Promise<TSmartAtopResponse<DelayItem[]>>, containing a list of delayed tasks.

Sample code

const currentHomeId = TSmartHomeManager.getInstance().getCurrentHomeId() ?? 0
const startTime = String(Date.now())
const endTime = String(Date.now() + 30 * 24 * 60 * 60 * 1000) // 30 天后
TSmartScene.getRuleDelayList(currentHomeId, startTime, endTime, 'Asia/Shanghai', 20).then((result) => {
  if (result && result.result) {
    console.info('The list of delayed tasks obtained successfully:', result.result)
  }
}).catch((error: Error) => {
  console.error('Failed to get the list of delayed tasks:', error)
})

Add a delayed task

API description

Add a delayed task to the scene.

static addRuleDelay(
  gid: number,
  ruleId: string,
  timeZoneId: string,
  delaySecond: number
): Promise<TSmartAtopResponse<boolean>>

Parameters

Parameter	Type	Description
gid	number	The ID of the specified home.
ruleId	string	The scene ID.
timeZoneId	string	The time zone ID. For example, `'Asia/Shanghai'`.
delaySecond	number	The delay duration, in seconds.

Return values

Returns Promise<TSmartAtopResponse<boolean>>. The result field being true indicates that a delayed task was added successfully.

Sample code

const currentHomeId = TSmartHomeManager.getInstance().getCurrentHomeId() ?? 0
TSmartScene.addRuleDelay(currentHomeId, this.sceneId, 'Asia/Shanghai', 300).then((result) => {
  if (result && result.result) {
    console.info('Delayed task added successfully')
  }
}).catch((error: Error) => {
  console.error('Failed to add delayed task:', error)
})

Remove a delayed task

API description

Remove a delayed task from the scene.

static removeRuleDelay(gid: number, ruleId: string): Promise<TSmartAtopResponse<boolean>>

Parameters

Parameter	Type	Description
gid	number	The ID of the specified home.
ruleId	string	The scene ID.

Return values

Returns Promise<TSmartAtopResponse<boolean>>. The result field being true indicates that a delayed task was removed successfully.

Sample code

const currentHomeId = TSmartHomeManager.getInstance().getCurrentHomeId() ?? 0
TSmartScene.removeRuleDelay(currentHomeId, this.sceneId).then((result) => {
  if (result && result.result) {
    console.info('Delayed task removed successfully')
  }
}).catch((error: Error) => {
  console.error('Failed to remove delayed task:', error)
})

Phone call and short message service (SMS)

Get value-added services

API description

Get a list of value-added services.

static getAddServiceAll(): Promise<TSmartAtopResponse<ServiceInfo[]>>

Return values

Returns Promise<TSmartAtopResponse<ServiceInfo[]>>, containing a list of value-added services.

Sample code

TSmartScene.getAddServiceAll().then((result) => {
  if (result && result.result) {
    console.info('The list of value-added services successfully obtained:', result.result)
  }
}).catch((error: Error) => {
  console.error('Failed to get the list of value-added services:', error)
})

Get phone contact information

API description

Get the phone contact information for a specified scene.

static getMobileInfo(sceneId: string): Promise<TSmartAtopResponse<VoiceServiceInfo>>

Parameters

Parameter	Type	Description
sceneId	string	The scene ID.

Return values

Returns Promise<TSmartAtopResponse<VoiceServiceInfo>>, containing phone contact information.

Sample code

TSmartScene.getMobileInfo(this.sceneId).then((result) => {
  if (result && result.result) {
    console.info('Phone contact information obtained successfully:', result.result)
  }
}).catch((error: Error) => {
  console.error('Failed to get phone contact information:', error)
})

Get SMS contact information

API description

Get the SMS contact information for a specified scene.

static getSMSInfo(sceneId: string): Promise<TSmartAtopResponse<SMSServiceInfo>>

Parameters

Parameter	Type	Description
sceneId	string	The scene ID.

Return values

Returns Promise<TSmartAtopResponse<SMSServiceInfo>>, containing SMS contact information.

Sample code

TSmartScene.getSMSInfo(this.sceneId).then((result) => {
  if (result && result.result) {
    console.info('SMS contact information obtained successfully:', result.result)
  }
}).catch((error: Error) => {
  console.error('Failed to get SMS contact information:', error)
})

Get remaining number of phone call reminders

API description

Get the remaining number of the phone call reminder service.

static getMobileLeftTimes(): Promise<TSmartAtopResponse<ServiceLeftTime>>

Return values

Return Promise<TSmartAtopResponse<ServiceLeftTime>>, containing information about the remaining number of phone call reminders.

Sample code

TSmartScene.getMobileLeftTimes().then((result) => {
  if (result && result.result) {
    console.info('The remaining number of phone call reminders obtained successfully:', result.result)
  }
}).catch((error: Error) => {
  console.error('Failed to get the remaining number of phone call reminders:', error)
})

Get remaining number of SMS reminders

API description

Get the remaining number of the SMS reminder service.

static getSMSLeftTimes(): Promise<TSmartAtopResponse<ServiceLeftTime>>

Return values

Return Promise<TSmartAtopResponse<ServiceLeftTime>>, containing information about the remaining number of SMS reminders.

Sample code

TSmartScene.getSMSLeftTimes().then((result) => {
  if (result && result.result) {
    console.info('The remaining number of SMS reminders obtained successfully:', result.result)
  }
}).catch((error: Error) => {
  console.error('Failed to get the remaining number of SMS reminders', error)
})

Others

Get scene style

API description

Get the background color and logo resources.

static getSceneStyle(): Promise<TSmartAtopResponse<SceneStyle>>

Return values

Returns Promise<TSmartAtopResponse<SceneStyle>>, containing the background color and logo resources.

Sample code

TSmartScene.getSceneStyle().then((result) => {
  if (result && result.result) {
    console.info('Scene style obtained successfully:', result.result)
  }
}).catch((error: Error) => {
  console.error('Failed to get scene style:', error)
})

Check support for the security guard switch

API description

Check whether the app supports the security guard switch.

static getSceneActionSupportSecurity(): Promise<TSmartAtopResponse<boolean>>

Return values

Returns Promise<TSmartAtopResponse<boolean>>. The result field being true indicates that the security guard switch is supported.

Sample code

TSmartScene.getSceneActionSupportSecurity().then((result) => {
  if (result && result.result) {
    console.info('App supports the security guard switch')
  } else {
    console.info('App does not support the security guard switch')
  }
}).catch((error: Error) => {
  console.error('Failed to get the support status of app security guard switch:', error)
})

Report positioning and location permission

API description

Report information about positioning and location permission.

static reportPermissionAndLatlon(
  hasPositionPermission: boolean,
  lon?: string,
  lat?: string
): void

Parameters

Parameter	Type	Description
hasPositionPermission	Boolean	Specifies whether the account has location permission.
lon	String	The longitude (optional).
lat	String	The latitude (optional).

Sample code

TSmartScene.reportPermissionAndLatlon(true, '120.123456', '30.123456')
console.info('Positioning and location permission information reported successfully')

Get guidance list

API description

Get the list of scene guidance banners.

static getGuideBannerAll(): Promise<TSmartAtopResponse<BannerList>>

Return values

Returns Promise<TSmartAtopResponse<BannerList>>, containing the list of guidance banners.

Sample code

TSmartScene.getGuideBannerAll().then((result) => {
  if (result && result.result) {
    console.info('Guidance list obtained successfully:', result.result)
  }
}).catch((error: Error) => {
  console.error('Failed to get the guidance list:', error)
})

Get limits on scene data

API description

Get limits on scene data.

static getCountLimit(relationId: number): Promise<TSmartAtopResponse<CountLimit>>

Parameters

Parameter	Type	Description
relationId	number	The relation (home) ID.

Return values

Returns Promise<TSmartAtopResponse<CountLimit>>, containing the limits on scene data.

Sample code

const currentHomeId = TSmartHomeManager.getInstance().getCurrentHomeId() ?? 0
TSmartScene.getCountLimit(currentHomeId).then((result) => {
  if (result && result.result) {
    console.info('The limits on scene data obtained successfully:', result.result)
  }
}).catch((error: Error) => {
  console.error('Failed to get the limits on scene data:', error)
})

Get standard scene information

API description

Get the information of standard scenes by device ID.

static getStandardInfo(meshIds: string[]): Promise<TSmartAtopResponse<StandardSceneInfo[]>>

Parameters

Parameter	Type	Description
meshIds	string[]	An array of device IDs for standard scenes.

Return values

Returns Promise<TSmartAtopResponse<StandardSceneInfo[]>>, containing a list of standard scenes.

Sample code

TSmartScene.getStandardInfo(['meshId1', 'meshId2']).then((result) => {
  if (result && result.result) {
    console.info('Standard scene information obtained successfully:', result.result)
  }
}).catch((error: Error) => {
  console.error('Failed to get standard scene information:', error)
})

Description of data types

NormalSceneBean

The scene data model, containing complete information about the scene.

Parameter	Type	Description
id	String	The scene ID.
name	String	The scene name.
enabled	Boolean	Indicates whether automation is enabled (only applicable to automation scenes).
ruleGenre	Number	The scene type: `1`: Tap-to-run `2`: Automation
outOfWork	Number	The state of a scene. `0`: Normal `1`: Invalid `2`: Anomaly
conditions	SceneCondition[]	The list of conditions (conditions only apply to automation scenes).
actions	SceneAction[]	The list of actions.
coverIcon	String	The URL of the cover icon for the tap-to-run scene.
displayColor	String	The background color of the scene (hexadecimal string, without `#`).
boundForPanel	Boolean	Indicates whether the scene is bound with a panel.
stickyOnTop	Boolean	Indicates whether the scene is displayed on the homepage.
boundForWiFiPanel	Boolean	Indicates whether the scene is bound with a Wi-Fi panel.
newLocalScene	Boolean	(Deprecated) Indicates whether the tap-to-run scene is managed by the same gateway.
localLinkage	Boolean	Indicates whether the automation is managed by the same gateway.
linkageType	Number	The scene type: `0`: Cloud `1`: Local (single gateway) `2`: LAN
arrowIconUrl	String	The URL of the scene arrow icon.
panelType	Number	The device type supported by the panel.
disableTime	Number	The time when the scene is disabled.
fullData	Boolean	Indicates whether the data is complete.
hasTimer	Boolean	Indicates whether the scene rules are set to execute with a delay.
background	String	(Deprecated) The URL of the background image.
scenarioRule	Boolean	Indicates whether it is a scene rule.
needCleanGidSid	Boolean	Indicates whether GID and SID need to be cleaned up.
roomIds	String[]	An array of room IDs.
categorys	String[]	An array of categories.
gwId	String	The ID of the central gateway that manages the scene.
validateDevice	Boolean	Indicates whether the device has been verified.
matchType	Number	The condition matching type. `1`: Meet any of the conditions. `2`: Meet all conditions.
ownerId	String	The ID of the scene owner.
stickOnTop	Boolean	Indicates whether the scene is pinned to the top.
boundForWiFiPanel	Boolean	Indicates whether the scene is bound with a Wi-Fi panel.
preConditions	PreCondition[]	The valid period of the scene, that is, an array of preconditions.
statusConditions	SceneCondition[]	The list of status conditions.
subMatchType	Number	The status condition matching type. `1`: Meet any of the conditions. `2`: Meet all conditions.
deviceIds	String[]	The set of device IDs associated with the scene rules.

SceneCondition

The data model of the scene condition.

Parameter	Type	Description
id	String	The condition ID (optional).
entityName	String	The condition name.
entityNameV2	String	The subtitle content for the sunrise and sunset schedule in Scene 2.0. For example, City/Recurring.
entityId	String	The device ID. This field works for device conditions.
entityType	Number	The condition type.
entitySubIds	String	The identifiers of the conditions other than devices.
defaultIconUrl	String	The default icon URL for the condition.
iconUrl	String	The icon URL for the condition.
exprDisplay	String	The name of the subtitle. Example: `"Temperature: less than -40°F"`.
productId	String	The product ID. This field works for device conditions.
productPic	String	The product image. This field works for device conditions.
devDelMark	Boolean	Indicates whether a device is removed. This field works for device conditions.
deleteDevIcon	String	The icon of the device displayed when it is removed. This field works for device conditions.
condType	Number	The condition matching type. `1`: Match against expressions `2`: Simple match
duration	String	The duration (optional).
expr	Array	The expression of the DP condition. Example: `[["$temp","<",-40]]`.
extraInfo	ConditionExtraInfo	The extension properties of the condition.

SceneAction

The data model of the scene action.

Parameter	Type	Description
id	String	The action ID.
actionId	String	The action ID (compatible field).
entityId	String	The device ID.
entityName	String	The device name.
actionExecutor	String	The action type.
executorProperty	Object	The execution details of an action.
extraProperty	Object	The additional information about an action.
actionDisplay	String	The displayed details of an action.
actionDisplayNew	Object	The displayed details of an action (new format).
devDelMark	Boolean	Indicates whether a device is removed.
devIcon	String	The device icon.
isDevOnline	Boolean	Indicates whether a device is online.
uiid	String	The UI ID.
productId	String	The product ID.
productPic	String	The product image.
deleteDevIcon	String	The icon of the device displayed when it is removed.
defaultIconUrl	String	The default icon URL.
uiInfo	UIInfo	The UI information.
i18nTime	Number	The international time.
pid	String	The product ID.
androidUiInfo	UIInfo	The UI information for Android.
relationGroup	RelationGroup	The relationship group.
ruleId	String	The rule ID (optional).
actionStrategy	String	The action strategy.
orderNum	Number	The sorting number (optional).

Prev DocMessage Management

Next DocFast Integration