saveLightScene – Tuya MiniApp

saveLightScene(data: SaveLightSceneParams)

Requires:

@tuya-miniapp/cloud-api≥1.2.0

Description

Create, edit, and save a lighting scene. This API saves the rule configuration of a lighting scene, including scene name, icon, execution actions, and other information.

Parameters

Parameter	Type	Required	Description
		Yes	Request parameters: ownerId (Home ID), sceneExpr (scene rule JSON data that contains the complete scene configuration; see the documentation "sceneExpr field description" for SaveExprData field details)

Return Value

Type: Promise<SaveLightSceneResult>

Scene info after saving (includes id, code, name, parentRegionId, ownerId, icon, enabled, status, sceneType, etc.; see the Return Parameters table in the documentation for details)

Referenced Types

interfaceSaveLightSceneResult

Property	Type	Description
`id`	number	Primary key ID
`code`	string	Scene code
`name`	string	Name
`parentRegionId`	string	Parent area ID
`ownerId`	string	Home ID
`uid`	string	User ID
`actualRuleId`	string	Actual rule ID
`icon`	string	Icon
`clickIcon`	string	Construct the click icon based on the icon field
`enabled`	number	Whether enabled (1: Enabled, 0: Disabled)
`status`	number	Status (0: Deleted, 1: Normal)
`sort`	number	Sort order
`sceneType`	1 \| 2 \| 3	Scene type (1: Basic scene on, 2: Basic scene off, 3: Custom scene)
`subSceneType`	number	Subtype; 0 is the default value and has no business meaning
		Execution action
		Condition; currently used only for distributed Bluetooth lighting scenes
`modifyUid`	string	ID of the user who updates the current record
`brightPercent`	number	Brightness percentage
`brightVisible`	boolean	Whether the brightness percentage is visible
`displayColor`	string	Background color
`background`	string	Background image
`scheduleBound`	boolean	Whether referenced by a schedule
`distributedAbnormalCode`	0 \| 1 \| 2 \| 100	Exception status of a distributed lighting scene (0: Normal, 1: Temporarily saved, 2: Not synchronized due to room device changes, 100: Other exception)
`distributeShortAddress`	number	Short address of the distributed rule
`matchType`	number	Condition match type; currently used only for distributed Bluetooth lighting scenes
`gmtCreate`	number	Creation time
`gmtModified`	number	Update time

Valid Values

`SaveLightSceneResult.sceneType`

Value	Description	Since
`1`	-	-
`2`	-	-
`3`	-	-

`SaveLightSceneResult.distributedAbnormalCode`

Value	Description	Since
`0`	-	-
`1`	-	-
`2`	-	-
`100`	-	-

Examples

Request example

import { saveLightScene } from '@tuya-miniapp/cloud-api';

const params = {
  ownerId: '194137',
  sceneExpr: JSON.stringify({
    actions: [
      {
        actionExecutor: 'lightDevice',
        entityId: 'vdevo176127325226099',
        entityName: 'Debug - Step Dimming - vdevo',
        executorProperty: {
          switch_led: true,
          work_mode: 'scene',
          smb_scene: '0132010100000000000003e80000320101000000000000000a0000',
        },
        extraProperty: {
          parentRegionId: '57939115',
          sceneName: '500 ms fade (warm light)',
          sceneId: '22304912',
          sceneType: 1,
          selectCellBackground: 'https://images.tuyacn.com/light/library/icon/img_scene.png',
        },
      },
    ],
    parentRegionId: 57939115,
    name: '500 ms fade (warm light)',
    displayColor: 'BA7B69',
    sceneType: 3,
    matchType: 1,
    icon: 'https://images.tuyacn.com/smart/rule/light/dianji_default.png',
  }),
};

saveLightScene(params)
  .then(result => {
    console.log('Scene saved successfully:', result);
  })
  .catch(error => {
    console.error('Failed to save scene:', error);
  });

Response example

{
  "id": 123456,
  "code": "light_scene_001",
  "name": "500 ms fade (warm light)",
  "parentRegionId": "57939115",
  "ownerId": "194137",
  "uid": "ay1234567890",
  "icon": "https://images.tuyacn.com/smart/rule/light/dianji_default.png",
  "enabled": 1,
  "status": 1,
  "sort": 1,
  "sceneType": 3,
  "displayColor": "BA7B69",
  "matchType": 1,
  "gmtCreate": 1766558627585,
  "gmtModified": 1766558627585
}

Additional notes

The sceneExpr parameter is a complex JSON string. Build a JavaScript object first, then convert it with JSON.stringify().
Some fields in the response are optional; the actual payload may vary depending on scene type and configuration.