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

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

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

Примечание

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

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

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,
            "status": 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

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

Да

status

String

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

  • online,
  • offline.

Если устройство недоступно, в поле передается значение offline, а в приложении Дом с Алисой отобразится статус устройства «не в сети». Если пользователь настроил отправку оповещений (Уведомления о состоянииНе в сетиУведомить о состоянии устройства «не в сети»), то ему также придет пуш-уведомление об обрыве соединения.

Пример запроса при изменении статуса устройства.

Нет

capabilities

Array of objects

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

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

properties

Array of objects

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

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


Объект capabilities

Параметр

Тип

Описание

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

<capability1>

Object

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

Нет

<capability2>

Object

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

Нет


Объект properties

Параметр

Тип

Описание

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

<property1>

Object

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

Нет

<property2>

Object

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

Нет

Пример запроса при изменении статуса устройства

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

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

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

Число с плавающей точкой с точностью до 6-9 десятичных знаков.

Cтрока, выделяется кавычками, например "Hello world".

Список пар "ключ": значение, разделенных запятой. Выделяется фигурными скобками {}.

{
  "name": "John",
  "surname": "Smith"
}

Массив элементов, разделенных запятой. Элементом могут быть стандартные элементы JSON: строка, число, true, false, объект или массив. Массив выделяется квадратными скобками []:

"cities": ["Moscow", "Tokyo", "New York"]

Идентификатор вызываемого навыка, присвоенный при создании.

Чтобы узнать идентификатор своего навыка, откройте его в консоли разработчика — идентификатор можно скопировать на вкладке Общие сведения, внизу страницы.