Scene Management

API list

Action	Description
scenes.add	Add a smart scene.
scenes.edit	Modify a smart scene.
scenes.delete	Delete a scene.
scenes.trigger	Trigger a scene
scenes.infos	Query scenes in a home.
scenes.default-pictures	Query default scene images.

Add a smart scene

API description

Add a scene to the specified home.

API endpoint

action: scenes.add

Request parameter

Parameter name	Type	Description	Required
home_id	Long	The home ID.	Yes
name	String	The scene name.	Yes
background	String	The background image.	Yes
actions	List	The list of actions.	Yes

Description of actions

Parameter name	Type	Description	Required
entity_id	String	The entity that performs the action. A device is currently supported. Set the value to a device ID.	Yes
executor_property	JSON	The property of the specified execution action.	Yes
action_executor	String	The type of action. Valid value: dpIssue. This is the default value.	Yes

Sample request

{
  "action": "scenes.add",
  "params": {
    "home_id": 2422120,
    "name":"Test of Adding a Scene",
    "background":"https://images.tuyacn.com/smart/rule/cover/sport.png",
    "actions":[
        {
            "executor_property":{
                "work_mode":"scene_2"
            },
            "action_executor":"dpIssue",
            "entity_id":"0120090568c63a89cb34"
        }
    ]
  }
}

Response parameter

Parameter name	Type	Description
code	Integer	The response code.
success	Boolean	Indicates whether the operation is successful. * true: succeeded * false: failed
msg	String	The error message that is returned if the API call fails. This parameter value is empty if the API call succeeds.
result	String	The scene ID.

Sample response

{
 "success": true,
 "t": 1541072348540,
 "result":"53IYSXI3gEn2w3Oc"
}

Modify a smart scene

API description

Modify a scene under the specified home.

API endpoint

action: scenes.edit

Request parameter

Parameter name	Type	Description	Required
home_id	Long	The home ID.	Yes
scene_id	String	The scene ID.	Yes
name	String	The scene name.	Yes
background	String	The background image.	Yes
actions	List	The list of actions.	Yes

Description of actions

Parameter name	Type	Description	Required
entity_id	String	The entity that performs the action. A device is currently supported. Set the value to a device ID.	Yes
executor_property	JSON	The property of the specified execution action.	Yes
action_executor	String	The type of action. Valid value: dpIssue. This is the default value.	Yes

Sample request

{
  "action": "scenes.edit",
  "params": {
    "home_id": 2422120,
    "scene_id": "53IYSXI3gEn2w3Oc",
    "name":"Test of Adding a Scene",
    "background":"https://images.tuyacn.com/smart/rule/cover/sport.png",
    "actions":[
        {
            "executor_property":{
                "work_mode":"scene_2"
            },
            "action_executor":"dpIssue",
            "entity_id":"0120090568c63a89cb34"
        }
    ]
  }
}

Response parameter

Parameter name	Type	Description
code	Integer	The response code.
success	Boolean	Indicates whether the operation is successful. * true: succeeded * false: failed
msg	String	The error message that is returned if the API call fails. This parameter value is empty if the API call succeeds.
result	Boolean	true is returned when the operation is successful.

Sample response

{
 "success": true,
 "t": 1541072348540,
 "result": true
}

Delete a scene

API description

Delete a scene of the specified home.

API endpoint

action: scenes.delete

Request parameter

Parameter name	Type	Description	Required
home_id	Long	The home ID.	Yes
scene_id	String	The scene ID.	Yes

Sample request

{
  "action": "scenes.delete",
  "params": {
    "home_id": 2422120,
    "scene_id": "53IYSXI3gEn2w3Oc"
  }
}

Response parameter

Parameter name	Type	Description
code	Integer	The response code.
success	Boolean	Indicates whether the operation is successful. * true: succeeded * false: failed
msg	String	The error message that is returned if the API call fails. This parameter value is empty if the API call succeeds.
result	Boolean	Indicates whether the scene is deleted successfully. true is returned when the operation is successful.

Sample response

{
 "success": true,
 "t": 1541072348540,
 "result": true
}

Trigger a scene

API description

Trigger a scene.

API endpoint

action: scenes.trigger

Request parameter

Parameter name	Type	Description	Required
home_id	Long	The home ID.	Yes
scene_id	String	The scene ID.	Yes

Sample request

{
  "action": "scenes.trigger",
  "params": {
    "home_id": 2422120,
    "scene_id": "53IYSXI3gEn2w3Oc"
  }
}

Response parameter

Parameter name	Type	Description
code	Integer	The response code.
success	Boolean	Indicates whether the operation is successful. * true: succeeded * false: failed
msg	String	The error message that is returned if the API call fails. This parameter value is empty if the API call succeeds.
result	Boolean	Indicates whether the scene is triggered successfully. true is returned when the operation is successful.

Sample response

{
 "success": true,
 "t": 1541072348540,
 "result": true
}

Query scenes in a home

API description

Query a list of scenes in a home.

API endpoint

action: scenes.infos

Request parameter

Parameter name	Type	Description	Required
home_id	Long	The home ID.	Yes

Sample request

{
  "action": "scenes.infos",
  "params": {
    "home_id": 2422120
  }
}

Response parameter

Parameter name	Type	Description
code	Integer	The response code.
success	Boolean	Indicates whether the operation is successful. * true: succeeded * false: failed
msg	String	The error message that is returned if the API call fails. This parameter value is empty if the API call succeeds.
result	Object	The returned result.

Description of result

Parameter name	Type	Description
scene_id	String	The scene ID.
update_time	String	The scene name.
background	String	The background image.
actions	List	The list of actions.

Description of actions

Parameter name	Type	Description
entity_id	String	The entity that performs the action. A device is currently supported. Set the value to a device ID.
executor_property	JSON	The property of the specified execution action.
action_executor	String	The type of action. Valid value: dpIssue.

Sample response

{
    "success":true,
    "t":1541071460239,
    "result":[
        {
            "scene_id":"53IYSXI3gEn2w3Oc",
            "name":"Turn on light bulb",
            "background":"https://images.tuyacn.com/smart/rule/cover/starry.png",
            "actions":[
                {
                    "entity_id":"0120090568c63a89cb34",
                    "executor_property":{
                        "work_mode":"scene_2"
                    },
                    "action_executor":"dpIssue"
                }
            ]
        },
        {
            "scene_id":"DKgx28KbdPfzEpvA",
            "name":"Morning",
            "background":"https://images.tuyacn.com/smart/rule/cover/sport2.png",
            "actions":[
                {
                    "entity_id":"012000715ccf7f4fb8b5",
                    "executor_property":{
                        "switch_led":true
                    },
                    "action_executor":"dpIssue"
                }
            ]
        }
    ]
}

Query default scene images

API description

Query a list of default scene images.

API endpoint

action: scenes.default-pictures

Request parameter

None.

Request parameter

{
  "action": "scenes.default-pictures"
}

Response parameter

Parameter name	Type	Description
code	Integer	The response code.
success	Boolean	Indicates whether the operation is successful. * true: succeeded * false: failed
msg	String	The error message that is returned if the API call fails. This parameter value is empty if the API call succeeds.
result	List	The returned result. A list of returned URLs of scene images is returned.

Sample response

{
    "result": [
        "https://images.tuyacn.com/smart/rule/cover/starry.png",
        "https://images.tuyacn.com/smart/rule/cover/air.png",
        "https://images.tuyacn.com/smart/rule/cover/sport.png",
        "https://images.tuyacn.com/smart/rule/cover/bedroom.png",
        "https://images.tuyacn.com/smart/rule/cover/work.png"
    ],
    "success": true,
    "t": 1583847698063
}