Notification about device state change

Notifies Yandex Smart Home about the changed device state.

Example situation when the current request is sent: the user passed the motion sensor, the sensor triggered.

Note

The notification service is available only for published skills. If your skill is still under development, you can make it private for the testing period so that external users can't access it.

Request format

POST https://dialogs.yandex.net/api/v1/skills/{skill_id}/callback/state

Request headers

Parameter	Description	Required
Authorization	Authorization token of the skill owner.	Yes
Content-Type	The format of sent/submitted data. Possible values: application/json.	Yes, in operations with HTTP POST

Request body format

{
    "ts": Float,
    "payload": {
        "user_id": String,
        "devices": [{
            "id": String,
            "status": String,
            "capabilities": [
                "<capability1>": Object,
                "<capability2>": Object
                    ...
                    ],
            "properties": [
                "<property1>": Object,
                "<property2>": Object
                    ...
                    ]
        }]
    }
}

Parameter	Type	Description	Required
ts	Float	Time of the event in seconds (UNIX timestamp format).	Yes
payload	Object	Object with devices.	Yes

payload object

Parameter	Type	Description	Required
user_id	String	User identifier sent in response to the Information about user devices request.	Yes
devices	Array of objects	Array of the devices that changed their state.	Yes

devices object

Parameter	Type	Description	Required
id	String	Device ID. It must be unique among all the manufacturer's devices.	Yes
status	String	Device status. Acceptable values: `online`. `offline`. If the device is unavailable, the `offline` value is passed in the field and the "offline" device status is displayed in the Home with Alice app. If the user has set up notifications via Уведомления о состоянии → Не в сети → Уведомить о состоянии устройства «не в сети» (State notifications → Offline → Notify about the device being offline), they will also receive a connection failure push notification. Example of a request when the device status changes.	No
capabilities	Array of objects	Array with information about the new states of capabilities of the devices.	Yes, if the `properties` parameter is omitted
properties	Array of objects	Array with information about the new states of properties.	Yes, if the `capabilities` parameter is omitted

capabilities object

Parameter	Type	Description	Required
<capability1>	Object	Describing a new capability state. For more information about the list of available capabilities and their parameters, see About capabilities. The format for describing a new state is the same as used in the response to the Information about the states of user devices.	No
<capability2>	Object	Describing a new capability state. For more information about the list of available capabilities and their parameters, see About capabilities. The format for describing a new state is the same as used in the response to the Information about the states of user devices.	No

properties object

Parameter	Type	Description	Required
<property1>	Object	Description of the new property state. For more information about the list of available properties and their parameters, see About properties. The format for describing a new state is the same as used in the response to the Information about the states of user devices.	No
<property2>	Object	Description of the new property state. For more information about the list of available properties and their parameters, see About properties. The format for describing a new state is the same as used in the response to the Information about the states of user devices.	No

Example of a request when the device status changes

curl -i -X POST 'https://dialogs.yandex.net/api/v1/skills/user-test-skill/callback/state' \
-H 'Authorization: OAuth 123qwe456a...' \
-H 'Content-Type: application/json' \
-d '{
  "ts": 1602703322.1,
  "payload": {
    "user_id": "provider-user-id-1",
    "devices": [{
      "id": "sensor-001-snsr",
      "status": "offline"
    }]
  }
}'

Response format

Response successful

Response with error

HTTP/1.1 202 Accepted

{
  "request_id": String,
  "status": "ok"
}

Parameter

Type

Description

Required

request_id

String

Request ID. Must be logged for the purpose of incident investigation.

Yes

status

String

Status of processing the request. Acceptable values:

ok.

Yes

HTTP/1.1 400

{
  "request_id": String,
  "status": "error",
  "error_code": String,
  "error_message": String
}

Parameter	Type	Description	Required
request_id	String	Request ID. Must be logged for the purpose of incident investigation.	Yes
status	String	Status of processing the request. Acceptable values: `error`.	Yes
error_code	String	Error code. Acceptable values: `BAD_REQUEST`; `UNKNOWN_USER`.	No
error_message	String	Error message.	No

Error codes

Example

Request

Response successful

Response with error

curl -i -X POST 'https://dialogs.yandex.net/api/v1/skills/user-test-skill/callback/state' \
-H 'Authorization: OAuth 123qwe456a...' \
-H 'Content-Type: application/json' \
-d '{
    "ts": 1602703322.1,
    "payload": {
        "user_id": "provider-user-id-1",
        "devices": [{
            "id": "sensor-001-snsr",
            "capabilities": [],
            "properties": [{
                "type": "devices.properties.event",
                "state": {
                    "instance": "motion",
                    "value": "detected"
                }
            }]
        }]
    }
}'

HTTP/1.1 202 Accepted

{
  "request_id": "75442486-0878-440c-9db1-a7006c25a39f",
  "status": "ok"
}

HTTP/1.1 400

{
  "request_id": "same-as-in-request",
  "status": "error",
  "error_code": "UNKNOWN_USER",
  "error_message": "User not found"
}

Was the article helpful?

Notification service operating protocol

Notification about device parameter change