Voice Platform Access

Last Updated on : 2025-05-30 01:56:03download

API List

Request method	API	Description
GET	/v1.0/voice/devices/{voice_id}/token	Obtain a voice token.
GET	/v1.0/token/{refresh_token}	Refresh token.
DELETE	/v1.0/voice/devices/{voice_id}/token	Invalidate a voice token.
POST	/v1.0/voice/execute	Voice service api.

API for Obtaining a Voice Token

API description

You can use this API to obtain a voice token.

API address

GET /v1.0/voice/devices/{voice_id}/token

Request Parameters

Parameter	Type	Position	Description	Mandatory
voice_id	String	URI	Unique ID of a voice device.	Yes
code	String	URI	Unique code of a voice brand, allocated upon entry of the voice brand.	Yes
industry_type	String	URI	Business type. The value is as follows:hotel.	Yes

Response Parameters

Parameter	Type	Description
code	Integer	Response code.Null indicates success.
success	Boolean	Request result. true: success false: failure
msg	String	Exception message.It is null when the request result is success.
t	Long	Response time, which is a 13-digit timestamp.
result	Object	Result object.

Parameters in result

Parameter	Type	Description
token	String	Voice token.
refresh_token	String	Refresh token, used for refreshing tokens.
expire_time	Long	Time available, Unit: s.

Request Example

GET /v1.0/voice/devices/***************/token?code=***********&industry_type=hotel

Success Response Example

{ 
  "result": { 
    "token"::"********************************",
    "refresh_token":"********************************",
    "expire_time":7200
  }, 
  "success": true, 
  "t": 1592899848757 
}

Failure Response Example

{
    "code":500,
    "msg":"system error,please contact the admin",
    "success":false,
    "t":1561378856383
}

API for Refreshing Tokens

API description

The OAuth token is currently valid for two hours for security concerns. After it has expired, you need to call refresh_token to get a new token.

Note: The access_token has a validity period limit but no limit on the number of times. The refresh_token has no limit of the validity period but only takes effect once.

API address

GET /v1.0/token/{refresh_token}

Request Parameters

Parameter	Type	Position	Description	Mandatory
refresh_token	String	URI	Refresh token.	Yes

Response Parameters

Parameter	Type	Description
code	Integer	Response code.Null indicates success.
success	Boolean	Request result. true: success false: failure
msg	String	Exception message.It is null when the request result is success.
t	Long	Response time, which is a 13-digit timestamp.
result	Object	Result object.

Parameters in result

Parameter	Type	Description
uid	String	Tuya user ID.
access_token	String	Access token.
expire_time	Integer	Validity period, in seconds.
refresh_token	String	Refresh token, used for refreshing tokens.

Request Example

GET /v1.0/token/******

Success Response Example

{ 
  "result": { 
    "token"::"********************************",
    "refresh_token":"********************************",
    "expire_time":7200
  }, 
  "success": true, 
  "t": 1592899848757 
}

API for Invalidating a Voice Token

API description

You can use this API to invalidate a voice token.

API address

DELETE /v1.0/voice/devices/{voice_id}/token

Request Parameters

Parameter	Type	Position	Description	Mandatory
voice_id	String	URI	Unique ID of a voice device.	Yes
code	String	URI	Unique code of a voice brand, allocated upon entry of the voice brand.	Yes
industry_type	String	URI	Business type. The value is as follows:hotel.	Yes

Response Parameters

Parameter	Type	Description
code	Integer	Response code.Null indicates success.
success	Boolean	Request result. true: success false: failure
msg	String	Exception message.It is null when the request result is success.
t	Long	Response time, which is a 13-digit timestamp.
result	Boolean	Operation result.

Request Example

DELETE /v1.0/voice/devices/****************/token?code=**********&industry_type=hotel

Success Response Example

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

Failure Response Example

{
  "code":500,
  "msg":"system error,please contact the admin",
  "success":false,
  "t":1561378856383
}

API for Discovering Devices

API description

You can use this API to discover devices.

API address

POST /v1.0/voice/execute

Request Parameters

Parameter	Type	Position	Description	Mandatory
message_id	String	BODY	Unique ID of a request.	Yes
version	String	BODY	API version.	Yes
command	Object	BODY	Command.	Yes

Parameters in command

Parameter	Type	Position	Description	Mandatory
interface	String	BODY	API name. The value is as follows:Tuya.Voice.Platform.Discovery	Yes
intent	String	BODY	Intent. The value is as follows: Discover	Yes

Response Parameters

Parameter	Type	Description
code	Integer	Response code.Null indicates success.
success	Boolean	Request result. true: success false: failure
msg	String	Exception message.It is null when the request result is success.
t	Long	Response time, which is a 13-digit timestamp.
result	Object	Result object.
message_id	String	Unique ID of a request.
version	String	API version.
command	Object	Command.

Parameters in result

Parameter	Type	Description
devices	Array	Device list.
scenes	Array	Scene list.

Parameters in result.devices

Parameter	Type	Description
category	String	Voice category.
device_name	String	Device name.
device_alias_list	Arrays	Device alias list.
position	String	Location. Optional. It is null when no location information is available.
device_id	String	Unique ID of a device.
supported_intents	Array	List of supported voice intents.

Parameters in result.scenes

Parameter	Type	Description
scene_id	String	Unique ID of a scene.
scene_name	String	Scene name.
supported_intents	Array	List of supported voice intents.

Request Example

POST /v1.0/voice/execute

{ 
  "message_id": "************", 
  "version": "1.0", 
  "command": { 
    "interface": "Tuya.Voice.Platform.Discovery", 
    "intent": "Discover"
  }
}

Success Response Example

{
  "success": true,
  "t":1566053034624,
  "message_id": "************", 
  "version": "1.0", 
  "command": { 
    "interface": "Tuya.Voice.Platform.Discovery", 
    "intent": "Discover" 
  }, 
  "result": { 
    "devices":[ 
      { 
        "device_id": "************", 
        "category": "light",
        "device_alias_list": ["alias1", "alias2"], 
        "device_name": "bedroom light",
        "position": "Test",
        "supported_intents": [ 
            "TurnOn", 
            "TurnOff" 
        ] 
      } 
    ],
    "scenes": [
      {
        "scene_id": "SCENE#qojnjY2Tc******",
        "scene_name": "All lights turn off", 
        "supported_intents": [ 
          "TurnOn" 
        ]
      },
      {
        "scene_id": "SCENE#vZyS8yfh8******",
        "scene_name": "All lights turn on",
        "supported_intents": [ 
          "TurnOn"
        ]
      }
    ] 
  } 
}

Failure Response Example

{ 
  "code":500,
  "msg":"system error,please contact the admin",
  "success":false,
  "t":1561378856383,
  "message_id": "******", 
  "version": "1.0", 
  "command": { 
    "interface": "Tuya.Voice.Platform.Discovery", 
    "intent": "Discover" 
  }
}

API for Querying Devices

API description

You can use this API to query devices.

API address

POST /v1.0/voice/execute

Request Parameters

Parameter	Type	Position	Description	Mandatory
message_id	String	BODY	Unique ID of a request.	Yes
version	String	BODY	API version.	Yes
command	Object	BODY	Command.	Yes
endpoint	Object	BODY	Device.	Yes

Parameters in command

Parameter	Type	Position	Description	Mandatory
interface	String	BODY	API name. The value is as follows:Tuya.Voice.Platform.Query	Yes
intent	String	BODY	Intent. The value is as follows: Query	Yes

Parameters in endpoint

Parameter	Type	Position	Description	Mandatory
device_id	String	BODY	Unique ID of a device.	Yes

Response Parameters

Parameter	Type	Description
code	Integer	Response code.Null indicates success.
success	Boolean	Request result. true: success false: failure
msg	String	Exception message.It is null when the request result is success.
t	Long	Response time, which is a 13-digit timestamp.
result	Object	Result object.
message_id	String	Unique ID of a request.
version	String	API version.
command	Object	Command.
endpoint	Object	Device.

Parameters in result

Parameter	Type	Description
properties	Array	Property list.

Parameters in result.properties

Parameter	Type	Description
name	String	Property name.
value	Object	Property value.

Parameters in endpoint

Parameter	Type	Description
device_id	String	Unique ID of a device.

Request Example

POST /v1.0/voice/execute

{ 
  "message_id": "************", 
  "version": "1.0", 
  "command": { 
    "interface": "Tuya.Voice.Platform.Query", 
    "intent": "Query",
  },
  "endpoint": { 
    "device_id": "******" 
  } 
}

Success Response Example

{
  "success": true,
  "t":1566053034624,
  "message_id": "************", 
  "version": "1.0", 
  "command": { 
    "interface": "Tuya.Voice.Platform.Query", 
    "intent": "Query" 
  },
  "endpoint": { 
    "device_id": "******" 
  }, 
  "result": { 
    "properties":[ 
      { 
        "name":"powerstate", // Power status. 
        "value":"on" 
      }, 
      { 
        "name":"color", // Color (HSV). 
        "value":{ 
          "h":350, 
          "s":40, 
          "v":40 
        } 
      }, 
      { 
        "name":"colorTemperature" // Color temperature (Kelvin). 
        "value":5000 
      }, 
      { 
        "name":"temperature", 
        "value":27 // Temperature (Celsius). 
      } 
    ] 
  } 
}

Failure Response Example

{ 
  "code":500,
  "msg":"system error,please contact the admin",
  "success":false,
  "t":1561378856383,
  "message_id": "******", 
  "version": "1.0", 
  "command": { 
    "interface": "Tuya.Voice.Platform.Query", 
    "intent": "Query" 
  },
  "endpoint": { 
    "device_id": "******" 
  }
}

API for Controlling Devices

API description

You can use this API to control devices.

API address

POST /v1.0/voice/execute

Request Parameters

Parameter	Type	Position	Description	Mandatory
message_id	String	BODY	Unique ID of a request.	Yes
version	String	BODY	API version.	Yes
command	Object	BODY	Command.	Yes
endpoint	Object	BODY	Device.	Yes

Parameters in command

Parameter	Type	Position	Description	Mandatory
interface	String	BODY	API name. The value is as follows:Tuya.Voice.Platform.Control	Yes
intent	String	BODY	Intent.	Yes
value	Object	BODY	Command value.	No

Parameters in endpoint

Parameter	Type	Position	Description	Mandatory
instance_id	String	BODY	Unique ID of a device.	Yes

Response Parameters

Parameter	Type	Description
code	Integer	Response code.Null indicates success.
success	Boolean	Request result. true: success false: failure
msg	String	Exception message.It is null when the request result is success.
t	Long	Response time, which is a 13-digit timestamp.
result	Object	Result object.
message_id	String	Unique ID of a request.
version	String	API version.
command	Object	Command.
endpoint	Object	Device.

Parameters in endpoint

Parameter	Type	Description
instance_id	String	Unique ID of a device.

Request Example

POST /v1.0/voice/execute

{ 
  "message_id": "************", 
  "version": "1.0", 
  "command": { 
    "interface": "Tuya.Voice.Platform.Control", 
    "intent": "SetBrightness",
    "value": 25
  },
  "endpoint": { 
    "instance_id": "******" 
  } 
}

Success Response Example

{
  "success": true,
  "t":1566053034624,
  "message_id": "************", 
  "version": "1.0", 
  "command": { 
    "interface": "Tuya.Voice.Platform.Control", 
    "intent": "SetBrightness" 
  },
  "endpoint": { 
    "instance_id": "******" 
  }
}

Failure Response Example

{ 
  "code":500,
  "msg":"system error,please contact the admin",
  "success":false,
  "t":1561378856383,
  "message_id": "******", 
  "version": "1.0", 
  "command": { 
    "interface": "Tuya.Voice.Platform.Control", 
    "intent": "SetBrightness" 
  },
  "endpoint": { 
    "instance_id": "******" 
  }
}

API for Triggering Scenes

API description

You can use this API to trigger scenes.

API address

POST /v1.0/voice/execute

Request Parameters

Parameter	Type	Position	Description	Mandatory
message_id	String	BODY	Unique ID of a request.	Yes
version	String	BODY	API version.	Yes
command	Object	BODY	Command.	Yes
endpoint	Object	BODY	Scene.	Yes

Parameters in command

Parameter	Type	Position	Description	Mandatory
interface	String	BODY	API name. The value is as follows:Tuya.Voice.Platform.Control	Yes
intent	String	BODY	Intent. The value is as follows:TurnOn	Yes

Parameters in endpoint

Parameter	Type	Position	Description	Mandatory
instance_id	String	BODY	Unique ID of a scene.	Yes

Response Parameters

Parameter	Type	Description
code	Integer	Response code.Null indicates success.
success	Boolean	Request result. true: success false: failure
msg	String	Exception message.It is null when the request result is success.
t	Long	Response time, which is a 13-digit timestamp.
result	Object	Result object.
message_id	String	Unique ID of a request.
version	String	API version.
command	Object	Command.
endpoint	Object	Scene.

Parameters in endpoint

Parameter	Type	Description
instance_id	String	Unique ID of a scene.

Request Example

POST /v1.0/voice/execute

{ 
  "message_id": "************", 
  "version": "1.0", 
  "command": { 
    "interface": "Tuya.Voice.Platform.Control", 
    "intent": "TurnOn"
  },
  "endpoint": { 
    "instance_id": "SCENE#******" 
  } 
}

Success Response Example

{
  "success": true,
  "t":1566053034624,
  "message_id": "************", 
  "version": "1.0", 
  "command": { 
    "interface": "Tuya.Voice.Platform.Control", 
    "intent": "TurnOn" 
  },
  "endpoint": { 
    "instance_id": "SCENE#******" 
  }
}

Failure Response Example

{ 
  "code":500,
  "msg":"system error,please contact the admin",
  "success":false,
  "t":1561378856383,
  "message_id": "******", 
  "version": "1.0", 
  "command": { 
    "interface": "Tuya.Voice.Platform.Control", 
    "intent": "TurnOn" 
  },
  "endpoint": { 
    "instance_id": "SCENE#******" 
  }
}

Error Code

The following are common business exceptions for this interface. For more exception errors, see Global Error Codes.

error code	explain
500	system error

Prev DocVoice Capacity