---
name: "saveLightScene"
mode: "api"
versionRequirements:
  - { name: "@tuya-miniapp/cloud-api", version: "1.2.0" }
---

## saveLightScene

> [VERSION] @tuya-miniapp/cloud-api >= 1.2.0

> 💡 This API relies on cloud capabilities; configure authorization in the Mini App Developer Platform (https://platform.tuya.com/miniapp/) under Development Settings > Cloud Capabilities. Steps: find the Mini App Lighting Scene capability card, click the Authorize button at the bottom right of the card, and complete the authorization.

### 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

`Params`

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `data` | `SaveLightSceneParams` | 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)

##### SaveLightSceneResult

| Property | Type | Description |
| --- | --- | --- |
| `id` | `number` | Primary key ID |
| `code` | `string` | Scene code |
| `name` | `string` | Name |
| `parentRegionId` | `string` | Parent region 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: not enabled) |
| `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 with no business meaning |
| `actions` | `LinkageActionVO[]` | Execution actions |
| `conditions` | `LinkageConditionVO[]` | Conditions; currently only distributed Bluetooth lighting scenes use this field |
| `modifyUid` | `string` | User ID that updated 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` | Abnormal status of distributed lighting scenes (0: normal, 1: temporary state, 2: unsynchronized due to room device changes, 100: other abnormal status) |
| `distributeShortAddress` | `number` | Short address of the distributed rule |
| `matchType` | `number` | Condition match type; currently only Bluetooth distributed lighting scenes use this field |
| `gmtCreate` | `number` | Creation time |
| `gmtModified` | `number` | Update time |

### Referenced Types

##### `interface` SaveLightSceneParams

| Property | Type | Description |
| --- | --- | --- |
| `ownerId` | `string` | Home ID |
| `sceneExpr` | `string` | Scene rule JSON data (string serialized from a SaveExprData object) |

##### `interface` LinkageActionVO

| Property | Type | Description |
| --- | --- | --- |
| `actionExecutor` | `string` | Executor type, e.g., "lightDevice" |
| `entityId` | `string` | Entity ID (device ID) |
| `entityName` | `string` | Entity name (device name) |
| `executorProperty` | `Record<string, any>` | Execution properties, including device control commands |
| `extraProperty` | `Record<string, any>` | Additional properties, including scene-related information |

##### `interface` LinkageConditionVO

| Property | Type | Description |
| --- | --- | --- |
| `conditionType` | `string` | Condition type |
| `entityId` | `string` | Entity ID |
| `expr` | `Record<string, any>` | Condition expression |


### Examples

#### Request example

```typescript
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

```json
{
  "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

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