Skip to main content

Interaction Types Reference

This reference provides information about interaction types, field descriptions, error handling, examples, and other specification requirements. In order to use SmartThings Schema, ensure that you have registered your Cloud Connector using the SmartThings CLI.

note

All parameters are required unless otherwise specified.

During your testing phase, monitor your server logs for Interaction Result. It will highlight any critical errors SmartThings finds with your integration.

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 is indicated in authentication.token.

For WWST approval, you must implement the following SmartThings interaction types:

  • discoveryRequest: SmartThings requests a list of devices. Automatic polling occurs every ~24 hours. The Discovery request is followed by the State Refresh request.
  • stateRefreshRequest: SmartThings requests the states of the indicated devices.
  • commandRequest: SmartThings requests that you issue commands for the indicated devices.
  • Callbacks allow your Cloud Connector to push a device's state to SmartThings:
    • Reciprocal Access Token Callbacks: Receive and refresh access tokens for use with a Callback interaction. Consists of the following interaction types:
      • grantCallbackAccess: Originates from SmartThings. Involved in initial token exchange.
      • accessTokenRequest: Originates from your Cloud Connector. Involved in initial token exchange.
      • accessTokenResponse: Originates from SmartThings. Involved in initial token exchange + refreshing the SmartThings token.
      • refreshAccessTokens: Originates from your Cloud Connector. Involved in refreshing the SmartThings token.
    • stateCallback is used by your Cloud Connector to update the state of a device that changed as a result of an interaction that did not originate from SmartThings.
    • discoveryCallback allows your Cloud Connector to perform on-demand discovery.
  • interactionResult notifies you of where issues were found in the response on a request from SmartThings Schema.
  • integrationDeleted notifies you when a connected service is deleted.
  • Error Responses can be appended with globalError or deviceError in your interaction type response.

Discovery​

Discovery is the first SmartThings request. Handle this request by retrieving a list of devices.

note

Automatic polling occurs approximately every 24 hours. The Discovery request is followed by the State Refresh request.

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"
  }
}

Below, we break down the request:

  • headers
    • schema: Schema type.
    • version: Schema version.
    • interactionType: Interaction type of payload.
    • requestId: A unique ID (requests sent from SmartThings use the UUID format) assigned to the 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 example response below).

note

Every device must be associated with a Device Profile or a deviceHandlerType. See Device Handler Types and Device Profiles for more info.

Example response

{
  "headers": {
    "schema": "st-schema",
    "version": "1.0",
    "interactionType": "discoveryResponse",
    "requestId": "abc-123-456"
  },
  "requestGrantCallbackAccess": true,
  "devices": [
    {
       "externalDeviceId": "partner-device-id-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": "partner-device-id-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>",
       "deviceUniqueId": "unique identifier of device"
     }
   ]
}

Here's a breakdown of the response:

  • headers
    • schema: Schema type.
    • version: Schema version.
    • interactionType: Interaction type of payload.
    • requestId: This must match the request ID sent in the original 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. requestGrantCallbackAccess should only be used if a refresh of callbackToken fails using the static refresh token, and the failure is not due to an internal server error or a timeout.
    • deviceUniqueId (O): Unique identifier for the device in the partner ecosystem. May or may not be the same as externalDeviceId.
note

See Error Responses for example JSON formats of global and device errors.

deviceUniqueId​

If you have an Alexa Skill, ensure you use the same value for deviceUniqueId that is used for your Alexa Skill customIdentifier

Categories​

The Categories response (mentioned above) is an optional parameter that helps define the kind of device that is being interacted with. SmartThings has an expanding list of device categories that work with our platform.

You can find the list of supported categories here.

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: A unique ID assigned to the request.
  • authentication: See Discovery section.
  • deviceState: Array of device states. See Callback section.

Example response

{
  "headers": {
    "schema": "st-schema",
    "version": "1.0",
    "interactionType": "stateRefreshResponse",
    "requestId": "abc-123-456"
  },
  "deviceState": [
    {
      "externalDeviceId": "partner-device-id-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.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: This must match the request ID sent in the original 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 the device. Use the syntax st.<capabilityName>.
      • attribute: Attribute of Capability.
      • value: The resource value.
      • unit: Unit of measure, if applicable. For example, "F" or "C" for temperature. Should not be present for attributes without units.
      • visibility: Optional fields controlling the display and storage of events
        • displayed: Show device events in the device history tab of the mobile app. Valid values are true or false. Generally defaults to true if unspecified, though some standard capabilities may default to false.
        • nonArchiveable: Don't put in long-term storage. Should only be set if legally or contractually required.
important

If your device supports a custom Device Profile, you must send the st.healthCheck Capability to indicate whether the device is online or offline. If the device is offline, only st.healthCheck is included in the states array.

important

If your device is deleted, you must send a DEVICE-DELETED device error enum as part of the state refresh response.

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-1",
      "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: A unique ID assigned to the request.
  • authentication: See Discovery section.
  • 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 the device. Use the syntax st.<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-1",
      "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
        }
      ]
    }
  ]
}
  • headers
    • schema: Schema type.
    • version: Schema version.
    • interactionType: Interaction type of payload.
    • requestId: This must match the requestId sent in the original request.
  • deviceState: (Optional) Array of device states. See State Refresh section.

If deviceState is sent in a command response, you must send a state update for all attributes that have changed.

deviceState is optional if it is not possible to know the correct state of the device during a command interaction. If deviceState is omitted, you must send a stateCallback containing all states that changed due to a command. stateCallback should be sent to SmartThings as soon as possible - ideally within five seconds to ensure a good user experience.

For devices that take longer to complete a state change, such as locks, the response may be longer than five seconds but must be before the SmartThings app times out and displays a network error (25 seconds).

important

If your device supports a custom Device Profile, you must send the st.healthCheck Capability to indicate whether the device is online or offline. If the device is offline, only st.healthCheck is included in the states array.

important

If your device is deleted, you must send a DEVICE-DELETED device error enum as part of the command response.

Example response (device error)

{
  "headers": {
    "schema": "st-schema",
    "version": "1.0",
    "interactionType": "<interactionResponse>",
    "requestId": "abc-123-456"
  },
  "deviceState": [
    {
      "externalDeviceId": "partner-device-id-1",
      "deviceError": [
        {
          "errorEnum": "DEVICE-DELETED",
          "detail": "more detail from the partner"
        }
      ]
    },
   {
      "externalDeviceId": "partner-device-id-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 you to push device state information to SmartThings.

The token in the JSON under authentication is the token received by you from SmartThings during the reciprocal OAuth phase.

The requestId in the callback JSON is generated by you. Be sure to use a unique identifier (SmartThings request IDs are sent in UUID format.)

requestId Requirements

Any unique 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.

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 seen 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: A unique ID assigned to the 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 in accessTokenRequest interaction.
    • clientId: Client ID.
  • callbackUrls:
    • oauthToken: Callback URL used in accessTokenRequest and refreshAccessTokens 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 the 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: A unique ID assigned to the request.
  • callbackAuthentication:
    • grantType: Authorization type.
    • code: Authorization code (provided in grantCallbackAccess interaction).
    • clientId: Client ID.
    • clientSecret: Client secret (found 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: This must match the requestId sent in the original request.
  • callbackAuthentication:
    • tokenType: Token type.
    • accessToken: Access token used in callback interactions.
    • refreshToken: Refresh token.
    • expiresIn: Expiration time (in seconds).
note

The access token expires in 24 hours.

The refresh token is static and will not change until a new grantCallbackAccess interaction is sent from SmartThings. This happens when either:

  • A user needs to re-login to the linked account.
  • Your integration requests a refresh of the callbackTokens by setting requestGrantCallbackAccess: true in a discoveryResponse.

requestGrantCallbackAccess should only be used if a refresh of callbackToken fails using the static refresh token, and the failure is not due to an internal server error or a timeout.

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: A unique ID assigned to the request.
  • callbackAuthentication:
    • grantType: Authorization type.
    • refreshToken: Refresh token.
    • clientId: Client ID.
    • clientSecret: Client secret (found in Developer Workspace).

Device State Callback​

JSON will be sent by you to the SmartThings Cloud without any request from SmartThings. This is used to update the state of a device that may have changed as a result of an interaction that did not originate from SmartThings, such as a command originating from your cloud or from 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": "partner-device-id-1",
            "states": [
                {
                    "component": "main",
                    "capability": "st.switch",
                    "attribute": "switch",
                    "value": "on",
                    "timestamp": 1568248946010
                },
                {
                    "component": "main",
                    "capability": "st.switchLevel",
                    "attribute": "level",
                    "value": 80,
                    "timestamp": 1568249946020
                }
            ]
        },
        {
            "externalDeviceId": "partner-device-id-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
                }
            ]
        }
    ]
}
  • 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. Must not contain personally identifiable information.
important

If your device state has changed, you must send the st.healthCheck Capability to indicate whether the device is online or offline.

important

If your device is deleted, you must send a DEVICE-DELETED device error enum as part of the device state callback response.

Response​

You should expect a 202 empty response. Most errors or validation issues will be delivered directly to the connector through an Interaction Result.

Expected Success Response​

    202 Accepted
note

See Error Responses for example JSON formats of global and device errors.

Discovery Callback​

A discovery callback interaction allows a third-party partner to perform on-demand discovery of devices.

  • headers
    • schema: Schema type.
    • version: Schema version.
    • interactionType: Interaction type of payload.
    • requestId: A unique ID assigned to the request.
  • authentication
    • tokenType: Token type.
    • token: Token issued by third-party cloud; the context for the request.

Below is an example request sent to the SmartThings Cloud:

{
  "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": "partner-device-id-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": "partner-device-id-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: A unique ID assigned to the 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. Must 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.

Response​

You should expect a 202 empty response. Most errors or validation issues will be delivered directly to the connector through an Interaction Result.

Expected Success Response​

    202 Accepted
note

See Error Responses for example JSON formats of global and device errors.

Interaction Result​

An interaction result is a notification to a third-party partner of where issues were found in the response on a request from SmartThings Schema.

  1. authentication: is not provided for users/interactions that SmartThings Schema has not been able to obtain valid access tokens from the partner.
  2. originatingInteractionType: the interaction type causing the interactionResult to be sent.
  3. globalError: only sent if there was a major issue with the originatingInteractionType message.
  4. 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​

This interaction notifies a third-party when a connected service is deleted.

tip

A SmartThings Schema integration is deleted from the SmartThings platform when any of the following conditions are met:

  • The user deletes all devices discovered by the integration.
  • The user removes the integration from "Linked services" on the SmartThings App.
  • A State Callback with the "INTEGRATION-DELETED" global error is received.

Request

{
  "headers": {
    "schema": "st-schema",
    "version": "1.0",
    "interactionType": "integrationDeleted",
    "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`: A unique ID assigned to the request. 
* `authentication`
    * `tokenType`: Token type.
    * `token`: Token issued by third-party cloud; the context for the request.

Response​

    204 No Content

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​

  • BAD-REQUEST: Bad request. Example detail values: st-schema body is missing, JSON parse of body failed, missing st-schema headers, missing st-schema authentication
  • INTEGRATION-DELETED: User has removed the integration; both accessToken and refreshToken are invalid. Indicates user must re-authorize.
  • INTEGRATION-OFFLINE: All devices in the integration are offline, or the integration is offline or unreachable.
  • INVALID-TOKEN
  • INVALID-INTERACTION-TYPE
  • UNSUPPORTED-GRANT-TYPE
  • INVALID-CODE
  • INVALID-CLIENT-SECRET
  • INVALID-CLIENT
  • TOKEN-EXPIRED: Token has expired.

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": "partner-device-id-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​

  • CAPABILITY-NOT-SUPPORTED: Command requested is not supported by the device.
  • DEVICE-DELETED: Device is deleted and cannot accept commands.
  • DEVICE-OFFLINE: Device is offline and cannot accept commands.
  • DEVICE-UNAVAILABLE: Device is temporarily unavailable for known reasons such as a firmware update or for maintenance.
  • RESOURCE-CONSTRAINT-VIOLATION: Value is out of range or not acceptable.
important

If your device is deleted, offline, or unavailable, you must send the appropriate DEVICE-DELETED, DEVICE-OFFLINE or DEVICE-UNAVAILABLE device error enum as part of the command response, device state callback, and state refresh.