Interaction types
This reference provides information about interaction types, field descriptions, error handling, examples, and other specification requirements.
Schema Info
- "schema": "st-schema"
- "version": "1.0"
Interaction Types
The interaction type is located in the payload headers.interactionType
. The token context for the request in indicated in authentication.token
.
You must implement the following SmartThings interaction types:
- Discovery: SmartThings requests a list of devices.
- State Refresh: SmartThings requests the states of the indicated devices.
- Command: SmartThings requests that you issue commands for the indicated devices.
Optional Interaction Types
- Callback: (Optional) Allows a third-party partner to push device state to SmartThings.
- Discovery callback: (Optional) Allows a third-party partner to perform on-demand discovery.
- Reciprocal access token: (Optional) Receive and refresh access tokens for use with a Callback interaction. Required for devices to qualify for Works with SmartThings certification.
- Integration deleted: (Optional) Notification to partner when connected service is deleted.
Discovery
Discovery is the first SmartThings request. Handle this request by retrieving a list of devices.
Example request
{
"headers": {
"schema": "st-schema",
"version": "1.0",
"interactionType": "discoveryRequest",
"requestId": "abc-123-456"
},
"authentication": {
"tokenType": "Bearer",
"token": "token received during oauth from partner"
}
}
headers
schema
: Schema type.version
: Schema version.interactionType
: Interaction type of payload.requestId
: Matching request ID from request.
authentication
tokenType
: Token type.token
: Token issued by third-party cloud; the context for the request.
In the response payload header, include the matching requestId
from the request. Also include the schema
, version
and corresponding interactionType
(e.g. discoveryResponse
).
Be sure to also include the payload requested. For the Discovery request, you need to include a list of devices (as seen in the below example).
deviceHandlerType
. See Device handler types
Example response
{
"headers": {
"schema": "st-schema",
"version": "1.0",
"interactionType": "discoveryResponse",
"requestId": "abc-123-456"
},
"requestGrantCallbackAccess": true,
"devices": [
{
"externalDeviceId": "pdevice-1",
"deviceCookie": {"updatedcookie": "old or new value"},
"friendlyName": "Kitchen Bulb",
"manufacturerInfo": {
"manufacturerName": "LIFX",
"modelName": "A19 Color Bulb",
"hwVersion": "v1 US bulb",
"swVersion": "23.123.231"
},
"deviceContext" : {
"roomName": "Kitchen",
"groups": ["Kitchen Lights", "House Bulbs"],
"categories": ["light", "switch"]
},
"deviceHandlerType": "c2c-rgbw-color-bulb",
"deviceUniqueId": "unique identifier of device"
},
{
"externalDeviceId": "pdevice-2",
"deviceCookie": {"updatedcookie": "old or new value"},
"friendlyName": "Toaster",
"manufacturerInfo": {
"manufacturerName": "LIFX",
"modelName": "Outlet",
"hwVersion": "v1 US outlet",
"swVersion": "3.03.11"
},
"deviceContext" : {
"roomName": "Living Room",
"groups": ["Hall Lights"]
},
"deviceHandlerType": "<DEVICE-PROFILE-ID>",
"requestGrantCallbackAccess": true,
"deviceUniqueId": "unique identifier of device"
}
]
}
headers
schema
: Schema type.version
: Schema version.interactionType
: Interaction type of payload.requestId
: Matching request ID from request.
devices
: Array of devices for user account.externalDeviceId
: Device ID at third-party cloud.deviceCookie
: Pass-through cookie for setting custom key/value pairs. Should not contain personally identifiable information and cannot be greater than 5 KB.friendlyName
: (Optional) Label of the device shown to the user.manufacturerInfo
: Manufacturer info for the device.manufacturerName
: Name of the manufacturer, preferably partner name.modelName
: Unique model number that identifies the device model.hwVersion
: (Optional) Hardware version.swVersion:
(Optional) Software/firmware version.
deviceContext
: (Optional) Device context info.roomName
: Location name associated with the device.groups
: Groups that include the device.categories
: (Optional) Categories associated with the device.
deviceHandlerType
: Device handler type name. When using a custom device profile, the value should be the device profile ID.requestGrantCallbackAccess
: A boolean used to determine whether partner needs access to callback token credentials again (O). When a partner’s callback access token has expired or the refresh token is stale, add "requestGrantCallbackAccess": true, to your discovery response for such users so that new callback access and refresh tokens can be received.deviceUniqueId (O)
: Unique identifier for the device in the partner ecosystem. May or may not be the same as externalDeviceId.
deviceUniqueId
If you have an Alexa skill , please send the same value for the customIdentifier field and vice vers
Categories
The Categories response (mentioned above) is an optional parameter. The category helps define the kind of device that is being interacted with. SmartThings has an expanding list of categories of devices that work with the system. Here is a list of the categories of devices that are currently supported. The system has a default icon based upon the category that is specified for the device.
- air-conditioner
- air-purifier
- blind
- bridges
- camera
- car
- contact-sensor
- cooktop
- dishwasher
- door
- door-bell
- dryer
- energy-meter
- fan
- garage-door
- generic-sensor
- health-tracker
- hub
- irrigation
- leak-sensor
- light
- mobile-presence
- motion-sensor
- multi-functional-sensor
- network-audio
- oven
- presence-sensor
- printer
- printer-multi-function
- range
- receiver
- refrigerator
- remote-controller
- robot-cleaner
- scanner
- security-panel
- set-top-box
- siren
- smart-lock
- smart-plug
- smoke-detector
- switch
- television
- thermostat
- upnp-media-renderer
- vent
- voice-assistance
- washer
- water-valve
- weight-scale
- wifi-router
- wine-cellar
State Refresh
Handle the State Refresh request by retrieving the device states for the indicated list of devices.
Example request
{
"headers": {
"schema": "st-schema",
"version": "1.0",
"interactionType": "stateRefreshRequest",
"requestId": "abc-123-456"
},
"authentication": {
"tokenType": "Bearer",
"token": "token received during oauth from partner"
},
"devices": [
{
"externalDeviceId": "partner-device-id-1",
},
{
"externalDeviceId": "partner-device-id-2"
}
]
}
headers
schema
: Schema type.version
: Schema version.interactionType
: Interaction type of payload.requestId
: Matching request ID from request.
authentication
: See above.deviceState
: Array of device states. See below.
Example response
{
"headers": {
"schema": "st-schema",
"version": "1.0",
"interactionType": "stateRefreshResponse",
"requestId": "abc-123-456"
},
"deviceState": [
{
"externalDeviceId": "pdevice-1",
"deviceCookie": {},
"states": [
{
"component": "main",
"capability": "st.switch",
"attribute": "switch",
"value": "on"
},
{
"component": "main",
"capability": "st.switchLevel",
"attribute": "level",
"value": 80
},
{
"component": "main",
"capability": "st.healthCheck",
"attribute": "healthStatus",
"value": "online"
},
{
"component": "main",
"capability": "st.colorControl",
"attribute": "hue",
"value": 0
},
{
"component": "main",
"capability": "st.colorControl",
"attribute": "saturation",
"value": 0
}
{
"component": "main",
"capability": "st.colorTemperature",
"attribute": "colorTemperature",
"value": 3500
}
]
}
]
}
headers
schema
: Schema type.version
: Schema version.interactionType
: Interaction type of payload.requestId
: Matching request ID from request.
deviceState
: Array of device states.externalDeviceID
: Third-party device ID.states
component
: Component of device. In most cases, the value will be "main".capability
: Capability of device. Use the syntaxst.<capabilityName>
.attribute
: Attribute of Capability.value
: The resource value.
st.healthCheck
Capability to indicate if the device is online
or offline
. If the device is offline, only st.healthCheck
is included in the states
array.
Command
Handle the Command request by triggering the commands for the list of devices.
Example request
{
"headers": {
"schema": "st-schema",
"version": "1.0",
"interactionType": "commandRequest",
"requestId": "abc-123-456"
},
"authentication": {
"tokenType": "Bearer",
"token": "token-received during oauth from partner"
},
"devices": [
{
"externalDeviceId": "partner-device-id",
"deviceCookie": {
"lastcookie": "cookie value"
},
"commands": [
{
"component": "main",
"capability": "st.colorControl",
"command": "setColor",
"arguments": [
{
"saturation": 91,
"hue": 0.8333333333333334
}
]
},
{
"component": "main",
"capability": "st.switchLevel",
"command": "setLevel",
"arguments": [80]
},
{
"component": "main",
"capability": "st.switch",
"command": "on",
"arguments": []
}
]
}
]
}
headers
schema
: Schema type.version
: Schema version.interactionType
: Interaction type of payload.requestId
: Matching request ID from request.
authentication
: See above.devices
externalDeviceId
: Device ID on third-party cloud.deviceCookie
: Received in the Discovery response.commands
: Array of commands.component
: Component of device. In most cases, the value will be "main".capability
: Capability of device. Use the syntaxst.<capabilityName>
.command
: Command name.arguments
: Array containing command arguments. If not applicable to the capability/attribute, will be empty.
Example response
{
"headers": {
"schema": "st-schema",
"version": "1.0",
"interactionType": "commandResponse",
"requestId": "abc-123-456"
},
"deviceState": [
{
"externalDeviceId": "partner-device-id",
"deviceCookie": {},
"states": [
{
"component": "main",
"capability": "st.colorControl",
"attribute": "hue",
"value": 0.8333333333333334
},
{
"component": "main",
"capability": "st.switch",
"attribute": "switch",
"value": "off"
},
{
"component": "main",
"capability": "st.switchLevel",
"attribute": "level",
"value": 80
},
{
"component": "main",
"capability": "st.healthCheck",
"attribute": "healthStatus",
"value": "online"
}
]
}
]
}
headers
schema
: Schema type.version
: Schema version.interactionType
: Interaction type of payload.requestId
: Matching request ID from request.
deviceState
: (Optional) Array of device states. See above.
deviceState
is optional if it's not possible to know the correct state of the device during the Command interaction.
If deviceState
is not provided in the Command interaction response, the deviceState
should be provided in a Callback interaction type within 25 seconds.
st.healthCheck
Capability to indicate if the device is online
or offline
. If the device is offline, only st.healthCheck
is included in the states
array.
Example response (device error)
{
"headers": {
"schema": "st-schema",
"version": "1.0",
"interactionType": "<interactionResponse>",
"requestId": "abc-123-456"
},
"deviceState": [
{
"externalDeviceId": "pdevice-1",
"deviceError": [
{
"errorEnum": "DEVICE-DELETED",
"detail": "more detail from the partner"
}
]
},
{
"externalDeviceId": "pdevice-2",
"states": [...]
}
]
}
deviceError
errorEnum
: Device error enum. See Error responses.detail
: Error details.
Example response (global error)
{
"headers": {
"schema": "st-schema",
"version": "1.0",
"interactionType": "<interactionResponse>",
"requestId": "abc-123-456"
},
"globalError": {
"errorEnum": "TOKEN-EXPIRED",
"detail": "more detail from the partner"
}
}
globalError
errorEnum
: Global error enum. See Error responses.detail
: Error details.
Callback
Callback interactions allow a third-party partner to push the latest device state information to SmartThings.
The Request ID in the callback JSON is generated by the partner.
Reciprocal Access Token
When SmartThings receives an access token (obtained in an OAuth integration) from a third party, it sends a callback authentication code
as below. The third party can use this code to request callback access tokens.
Grant callback access example
{
"headers": {
"schema": "st-schema",
"version": "1.0",
"interactionType": "grantCallbackAccess",
"requestId": "abc-123-456"
},
"authentication" : {
"tokenType": "Bearer",
"token": "Token received during oauth from partner"
},
"callbackAuthentication": {
"grantType": "authorization_code",
"scope": "callback_access",
"code": "xxxxxxxxxxx",
"clientId": "Client ID given to partner in Workspace during app creation"
},
"callbackUrls": {
"oauthToken": "Callback URL for access-token-request.json and refresh-access-tokens.json requests",
"stateCallback": "Callback URL for state-callback.json updates"
}
}
headers
schema
: Schema type.version
: Schema version.interactionType
: Interaction type of payload.requestId
: Matching request ID from request.
authentication
:tokenType
: Token type.token
: Token issued by third-party cloud; the context for the request.
callbackAuthentication
:grantType
: Authorization type.scope
: Authorization scope.code
: Authorization code to be used inaccessTokenRequest
interaction.clientId
: Client ID.
callbackUrls
:oauthToken
: Callback URL used inaccessTokenRequest
andrefreshAccessTokens
interactions.stateCallback
: Callback URL for providing state callbacks.
Use an HTTPS POST
call to the above oauthToken
URL to request a callback access token. A third party uses the callback access token to call into SmartThings Cloud.
Example access token request
{
"headers": {
"schema": "st-schema",
"version": "1.0",
"interactionType": "accessTokenRequest",
"requestId": "abc-123-456"
},
"callbackAuthentication": {
"grantType": "authorization_code",
"code": "xxxxxxxxxxx",
"clientId": "client id given to partner in dev-workspace during app creation",
"clientSecret": "client secret given to partner in dev-workspace during app creation"
}
}
headers
schema
: Schema type.version
: Schema version.interactionType
: Interaction type of payload.requestId
: Matching request ID from request.
callbackAuthentication
:grantType
: Authorization type.code
: Authorization code (provided ingrantCallbackAccess
interaction).clientId
: Client ID.clientSecret
: Client secret (obtained in Developer Workspace).
Example access token response
{
"headers": {
"schema": "st-schema",
"version": "1.0",
"interactionType": "accessTokenResponse",
"requestId": "abc-123-456"
},
"callbackAuthentication": {
"tokenType": "Bearer",
"accessToken": "xxxxxxxxxxx",
"refreshToken": "yyyyyyyyyyy",
"expiresIn": 86400
}
}
headers
schema
: Schema type.version
: Schema version.interactionType
: Interaction type of payload.requestId
: Matching request ID from request.
callbackAuthentication
:tokenType
: Token type.accessToken
: Access token used incallback
interactions.refreshToken
: Refresh token.expiresIn
: Expiration time (in seconds).
If the access token has expired, use the provided refreshToken
to request a new access token at the oauthToken
URL used previously.
Refresh access token example
{
"headers": {
"schema": "st-schema",
"version": "1.0",
"interactionType": "refreshAccessTokens",
"requestId": "abc-123-456"
},
"callbackAuthentication": {
"grantType": "refresh_token",
"refreshToken": "xxxxxxxxxxx",
"clientId": "client id given to partner in dev-workspace during app creation",
"clientSecret": "client secret given to partner in dev-workspace during app creation"
}
}
headers
schema
: Schema type.version
: Schema version.interactionType
: Interaction type of payload.requestId
: Matching request ID from request.
callbackAuthentication
:grantType
: Authorization type.refreshToken
: Refresh token.clientId
: Client ID.clientSecret
: Client secret (obtained in Developer Workspace).
Device State Callback
JSON will be set by the partner to the SmartThings cloud without any request from SmartThings. This should be used to update the state of the device that may have changed from an interaction caused by a non-SmartThings command (i.e command originating from the partner’s cloud triggered by a command from the native app or by manually controlling the device).
Example request
{
"headers": {
"schema": "st-schema",
"version": "1.0",
"interactionType": "stateCallback",
"requestId": "abc-123-456"
},
"authentication": {
"tokenType": "Bearer",
"token": "token-received from SmartThings for callbacks"
},
"deviceState": [
{
"externalDeviceId": "pdevice-1",
"states": [
{
"component": "main",
"capability": "st.switch",
"attribute": "switch",
"value": "on",
"timestamp": 1568248946010
},
{
"component": "main",
"capability": "st.switchLevel",
"attribute": "level",
"value": 80,
"timestamp": 1568249946020
},
{
"component": "main",
"capability": "st.healthCheck",
"attribute": "healthStatus",
"value": "online",
"timestamp": 1568251946030
}
]
},
{
"externalDeviceId": "pdevice-2",
"states": [
{
"component": "main",
"capability": "st.switch",
"attribute": "switch",
"value": "off",
"timestamp": 1568254946010
},
{
"component": "main",
"capability": "st.switchLevel",
"attribute": "level",
"value": 80,
"timestamp": 1568255946020
},
{
"component": "main",
"capability": "st.healthCheck",
"attribute": "healthStatus",
"value": "offline",
"timestamp": 1568257946030
}
]
}
]
}
headers
: See above.authentication
tokenType
: Token type.token
: Token received from SmartThings.
deviceState
: (Optional) Array of device states.externalDeviceID
: Third-party device ID.deviceCookie
: (Optional) Pass-through cookie for setting custom key/value pairs. Should not contain personally identifiable information.
Discovery Callback
A discovery callback interaction allows a third-party partner to perfom on-demand discovery of devices.
headers
schema
: Schema type.version
: Schema version.interactionType
: Interaction type of payload.requestId
: Any string of alphanumeric characters and dashes less than 128 characters is valid, but a version 4 UUID, which is a UUID generated from random numbers, is recommended.
authentication
tokenType
: Token type.token
: Token issued by third-party cloud; the context for the request.
Example response
{
"headers": {
"schema": "st-schema",
"version": "1.0",
"interactionType": "discoveryCallback",
"requestId": "abc-123-456"
},
"authentication": {
"tokenType": "Bearer",
"token": "token-recevied from SmartThings for callbacks"
},
"devices": [
{
"externalDeviceId": "pdevice-1",
"deviceCookie": {"updatedcookie": "old or new value"},
"friendlyName": "Kitchen Bulb",
"manufacturerInfo": {
"manufacturerName": "LIFX",
"modelName": "A19 Color Bulb",
"hwVersion": "v1 US bulb",
"swVersion": "23.123.231"
},
"deviceContext" : {
"roomName": "Kitchen",
"groups": ["Kitchen Lights", "House Bulbs"]
},
"deviceHandlerType": "c2c-rgbw-color-bulb"
},
{
"externalDeviceId": "pdevice-2",
"deviceCookie": {"updatedcookie": "old or new value"},
"friendlyName": "Toaster",
"manufacturerInfo": {
"manufacturerName": "LIFX",
"modelName": "Outlet",
"hwVersion": "v1 US outlet",
"swVersion": "3.03.11"
},
"deviceContext" : {
"roomName": "Living Room",
"groups": ["Hall Lights"]
},
"deviceHandlerType": "<DEVICE-PROFILE-ID>"
}
]
}
headers
schema
: Schema type.version
: Schema version.interactionType
: Interaction type of payload.requestId
: Matching request ID from request.
devices
: Array of devices for user account.externalDeviceId
: Device ID at third-party cloud.deviceCookie
: Pass-through cookie for setting custom key/value pairs. Should not contain personally identifiable information and cannot be greater than 5 KB.friendlyName
: (Optional) Label of the device shown to the user.manufacturerInfo
: Manufacturer info for the device.manufacturerName
: Name of the manufacturer, preferably partner name.modelName
: Unique model number that identifies the device model.hwVersion
: (Optional) Hardware version.swVersion:
(Optional) Software/firmware version.
deviceContext
: (Optional) Device context info.roomName
: Location name associated with the device.groups
: Groups that include the device.categories
: (Optional) Categories associated with the device.
deviceHandlerType
: Device handler type name. When using a custom device profile, the value should be the device profile ID.
Interaction Result
Notification to the partner where issues are found in the response on a request from SmartThings Schema.
- authentication: is not provided for users / interatctions that ST schema has not been able to obtain valid access tokens from the partner.
- originatingInteractionType: the interaction type causing the interactionResult to be sent.
- globalError: only sent if there was a major issue with the originatingInteractionType message.
- deviceState: only sent for and when there are issues with individual devices, devices with no issues will not be included.
{
"headers": {
"schema": "st-schema",
"version": "1.0",
"interactionType": "interactionResult",
"requestId": "abc-123-456"
},
"authentication": {
"tokenType": "Bearer",
"token": "token-recevied during oauth from partner"
},
"originatingInteractionType" : <interactionResponse>,
"globalError": {
"errorEnum": "<enum>",
"detail": "messageDetail"
},
"deviceState": [
{
"externalDeviceId": "pdevice-1",
"deviceError": [
{
"errorEnum": "<enum>",
"detail": "messageDetail"
}
]
}
]
}
Integration Deleted
Notification to partner when connected service is deleted.
{
"headers": {
"schema": "st-schema",
"version": "1.0",
"interactionType": "integrationDeleted",
"requestId": "abc-123-456"
},
"authentication": {
"tokenType": "Bearer",
"token": "token received during oauth from partner"
}
}
204 No Content
headers
schema
: Schema type.version
: Schema version.interactionType
: Interaction type of payload.requestId
: Matching request ID from request.
authentication
tokenType
: Token type.token
: Token issued by third-party cloud; the context for the request.
Error Responses
Errors can be appended using global errors or device errors in your interaction type response.
Example global error
{
"headers": {
"schema": "st-schema",
"version": "1.0",
"interactionType": "stateRefreshResponse",
"requestId": "abc-123-456"
},
"authentication": {
"tokenType": "Bearer",
"token": "token-issued-by-3rd-party"
},
"globalError": {
"errorEnum": "TOKEN-EXPIRED",
"detail": "The token has expired"
},
"deviceState": []
}
Append a globalError
field to the root of your JSON response for an interaction type.
errorEnum
: Global error enum type (see below).details
: Message for the error.
Global error enum types
TOKEN-EXPIRED
: Token has expired.INTEGRATION-DELETED
: User has removed the integration, so bothaccessToken
andrefreshToken
are invalid. Used to indicate user needs to re-authorize.BAD-REQUEST
: Bad request. Exampledetail
values:st-schema body is missing
,JSON parse of body failed
,missing st-schema headers
,missing st-schema authentication
INVALID-TOKEN
INVALID-INTERACTION-TYPE
UNSUPPORTED-GRANT-TYPE
INVALID-CODE
INVALID-CLIENT-SECRET
INVALID-CLIENT
Example device error
{
"headers": {
"schema": "st-schema",
"version": "1.0",
"interactionType": "stateRefreshResponse",
"requestId": "abc-123-456"
},
"authentication": {
"tokenType": "Bearer",
"token": "token-issued-by-3rd-party"
},
"deviceState": [
{
"externalDeviceId": "pdevice-1",
"deviceError": [
{
"errorEnum": "DEVICE-DELETED",
"detail": "more detail from the partner"
}
]
}
]
}
Append a deviceError
field to the stateRefreshResponse
or commandResponse
interaction response.
errorEnum
: Device error enum type (see below).details
: Message for the error.
Device error enum types
DEVICE-DELETED
: Device is deleted and cannot accept commands.RESOURCE-CONSTRAINT-VIOLATION
: Value is out of range or not acceptable.DEVICE-UNAVAILABLE
: Device is unavailable because of a f/w update, maintenance, etc. For use when temporarily unavailable for known reasons.CAPABILITY-NOT-SUPPORTED
: Command requested is not supported by the device.