Notification about device state change

Notifies Yango Smart Home about the changed device state.

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

  1. Request format
  2. Response format
  3. Example
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.yango.com/api/v1/skills/{skill_id}/callback/state
skill_id

ID of the skill invoked (assigned at creation).

To find out your skill ID, open the skill in your developer console: you can copy the skill ID on the General information tab (at the bottom of the page).

skill_id

ID of the skill invoked (assigned at creation).

To find out your skill ID, open the skill in your developer console: you can copy the skill ID on the General information tab (at the bottom of the page).

Request headers

Header 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
Header 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,
            "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
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
id String Device ID. It must be unique among all the manufacturer's devices. Yes
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
<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 request. 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 request. No
properties object
<property1> Object Describing a new state of a property. For a more detailed 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 request. No
<property2> Object Describing a new state of a property. For a more detailed 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 request. No
Parameter Type Description Required
ts Float Time of the event in seconds (UNIX timestamp format). Yes
payload Object Object with devices. Yes
payload object
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
id String Device ID. It must be unique among all the manufacturer's devices. Yes
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
<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 request. 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 request. No
properties object
<property1> Object Describing a new state of a property. For a more detailed 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 request. No
<property2> Object Describing a new state of a property. For a more detailed 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 request. No

Response format

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

Example

curl -i -X POST 'https://dialogs.yango.com/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"
                }
            }]
        }]
    }
}'