Implement the Schema

Discovery

You should first implement the Discovery interaction type. This is the first SmartThings request your service will need to handle.

Example Discovery request

{
    "headers": {
        "schema": "st-schema",
        "version": "1.0",
        "interactionType": "discoveryRequest",
        "requestId": "abc-123-456"
    },
    "authentication" : {
        "tokenType": "Bearer",
        "token": "token-issued-from-3rd-party"
    }
}

Handling the interaction request

The request payload has a headers field. Determine the interaction type using the value in headers.interactionType.

The token value in authentication.token represents the token your cloud has issued and is the context for the request. For example, you will return devices valid for this token within your own cloud.

Interaction response

• 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).
• Every device must be associated with a deviceHandlerType. See Device handler types

Example Discovery response

{
    "headers": {
        "schema": "st-schema",
        "version": "1.0",
        "interactionType": "discoveryResponse",
        "requestId": "abc-123-456"
    },
    "devices": [
        {
            "externalDeviceId": "3rd-party-id-000-aaa-bbb-ccc",
            "deviceCookie": {"updatedcookie": "old or new value"},
            "friendlyName": "Kitchen Bulb",
            "manufacturerInfo": {
                "manufacturerName": "XYZ-Company",
                "modelName": "XYZ Color Bulb",
                "hwVersion": "v1 XYZ Bulb",
                "swVersion": "1.123.123"
            },
            "deviceContext" : {
                "roomName": "Kitchen",
                "groups": ["Kitchen Lights", "House Bulbs"],
                "categories": ["light", "switch"]
            },
            "deviceHandlerType": "c2c-rgbw-color-bulb"
        },
        {
            "externalDeviceId": "3rd-party-id-111-aaa-bbb-ccc",
            "deviceCookie": {"updatedcookie2": "old or new value"},
            "friendlyName": "Living Room Bulb",
            "manufacturerInfo": {
                "manufacturerName": "XYZ-Company",
                "modelName": "XYZ Color Bulb",
                "hwVersion": "v1 XYZ Bulb",
                "swVersion": "1.123.123"
            },
            "deviceContext" : {
                "roomName": "Living Room",
                "groups": ["Hall Lights"],
                "categories": ["light"]                
            },
            "deviceHandlerType": "c2c-rgbw-color-bulb"
        }
    ]
}

Next steps

To implement the remaining interaction types, see the SmartThings Schema reference. The reference also includes information for using callbacks and error handling.