Уведомление об изменении состояний устройств

Уведомляет платформу умного дома об изменившемся состоянии устройств.

Пример ситуации, в которой отправляется текущий запрос: пользователь прошел мимо датчика движения, датчик сработал.

Примечание

Сервис уведомлений доступен только для опубликованных навыков. Если вы только разрабатываете навык, то можно сделать его приватным на время тестирования и не открывать для внешних пользователей.

Формат запроса

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

Заголовки запроса

Параметр

Описание

Обязательный

Authorization

Авторизационный токен владельца навыка.

Да

Content-Type

Формат передаваемых/отправляемых данных. Возможные значения: application/json.

Да, в операциях с http-методом POST

Формат тела запроса

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

Параметр

Тип

Описание

Обязательный

ts

Float

Время возникновения события в секундах, формат unix timestamp.

Да

payload

Object

Объект с устройствами.

Да

Объект payload

Параметр

Тип

Описание

Обязательный

user_id

String

Идентификатор пользователя, который был передан в ответе на запрос Информация об устройствах пользователя.

Да

devices

Array of objects

Массив с устройствами, которые изменили свое состояние.

Да

Объект devices

Параметр

Тип

Описание

Обязательный

id

String

Идентификатор устройства. Должен быть уникален среди всех устройств производителя.

Да

capabilities

Array of objects

Массив с информацией о новых состояниях умений устройств.

Да, если отсутствует properties

properties

Array of objects

Массив с информацией о новых состояниях свойств.

Да, если отсутствует capabilities

Объект capabilities

Параметр

Тип

Описание

Обязательный

<capability1>

Object

Описание нового состояния умения. Подробнее со списком доступных умений и их параметрами можно ознакомиться в разделе Об умениях. Формат описания нового состояния совпадает с форматом, который используется в ответе на запрос Информация о состояниях устройств пользователя.

Нет

<capability2>

Object

Описание нового состояния умения. Подробнее со списком доступных умений и их параметрами можно ознакомиться в разделе Об умениях. Формат описания нового состояния совпадает с форматом, который используется в ответе на запрос Информация о состояниях устройств пользователя.

Нет

Объект properties

Параметр

Тип

Описание

Обязательный

<property1>

Object

Описание нового состояния свойства. Подробнее со списком доступных свойств и их параметрами можно ознакомиться в разделе О свойствах. Формат описания нового состояния совпадает с форматом, который используется в ответе на запрос Информация о состояниях устройств пользователя.

Нет

<property2>

Object

Описание нового состояния свойства. Подробнее со списком доступных свойств и их параметрами можно ознакомиться в разделе О свойствах. Формат описания нового состояния совпадает с форматом, который используется в ответе на запрос Информация о состояниях устройств пользователя.

Нет

Формат ответа

HTTP/1.1 202 Accepted

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

Параметр

Тип

Описание

Обязательный

request_id

String

Идентификатор запроса. Необходимо логировать для расследования инцидентов.

Да

status

String

Статус обработки запроса. Допустимые значения:

  • ok.

Да

 
HTTP/1.1 400

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

Параметр

Тип

Описание

Обязательный

request_id

String

Идентификатор запроса. Необходимо логировать для расследования инцидентов.

Да

status

String

Статус обработки запроса. Допустимые значения:

  • error.

Да

error_code

String

Код ошибки. Допустимые значения:

  • BAD_REQUEST;
  • UNKNOWN_USER.

Нет

error_message

String

Сообщение об ошибке.

Нет

Коды ошибок

Пример

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

Предыдущая
Протокол работы сервиса уведомлений
Следующая
Уведомление об изменении параметров устройств