--- metadata: - name: generator content: Diplodoc Platform v5.66.0 alternate: - https://yandex.ru/dev/dialogs/smart-home/doc/en/reference-alerts/post-skill_id-callback-state.md - https://yandex.ru/dev/dialogs/smart-home/doc/ru/reference-alerts/post-skill_id-callback-state.md - href: https://yandex.ru/dev/dialogs/smart-home/doc/ru/reference-alerts/post-skill_id-callback-state.md type: text/markdown title: Markdown version - href: https://yandex.ru/dev/dialogs/smart-home/doc/ru/llms.txt?revision=r21995741 rel: describedby --- > **Documentation Index:** Fetch the complete configuration index at https://yandex.ru/dev/dialogs/smart-home/doc/ru/llms.txt?revision=r21995741 # Уведомление об изменении состояния устройства Уведомляет платформу умного дома об изменившемся состоянии устройств. Пример ситуации, в которой отправляется текущий запрос: пользователь прошел мимо датчика движения, датчик сработал. Исчерпывающий перечень событий, при которых отправка этого запроса обязательна, — в разделе [Требования к уведомлениям](https://yandex.ru/dev/dialogs/smart-home/doc/ru/concepts/notifications-requirements.md#state-triggers). {% note info "Условие работы сервиса уведомлений" %} Уведомления принимаются, если навык был опубликован хотя бы один раз, включая приватную публикацию. На черновике навыка, который ни разу не публиковали, сервис уведомлений не работает — отлаживайте отправку уведомлений на опубликованном навыке. Подробнее см. в разделе [Требования к уведомлениям](https://yandex.ru/dev/dialogs/smart-home/doc/ru/concepts/notifications-requirements.md). {% endnote %} ## Формат запроса {#input} ```bash translate=no POST https://dialogs.yandex.net/api/v1/skills/{[skill_id](*skill_id)}/callback/state ``` #### Заголовки запроса {#headers} #| || **Параметр** | **Описание** | **Обязательный** || || Authorization | Авторизационный [токен владельца навыка](https://yandex.ru/dev/dialogs/smart-home/doc/ru/reference-alerts/resources-alerts.md#oauth). | Да || || Content-Type | Формат передаваемых/отправляемых данных. Возможные значения: application/json. | Да, в операциях с http-методом POST || |# #### Формат тела запроса {#structure-in} ```json translate=no { "ts": Float, "payload": { "user_id": String, "devices": [{ "id": String, "status": String, "capabilities": [ "": Object, "": Object ... ], "properties": [ "": Object, "": Object ... ] }] } } ``` #| || **Параметр** | **Тип** | **Описание** | **Обязательный** || || ts | [Float](*float) | Время возникновения события в секундах, формат unix timestamp. Передается время наступления события, а не время отправки запроса. Подробнее — в разделе [Требования к `ts`](https://yandex.ru/dev/dialogs/smart-home/doc/ru/reference-alerts/post-skill_id-callback-state.md#ts-requirements). | Да || || payload | [Object](*object) | Объект с устройствами. | Да || |#
**Объект `payload`** #| || **Параметр** | **Тип** | **Описание** | **Обязательный** || || user_id | [String](*string) | Идентификатор пользователя, который был передан в ответе на запрос [Информация об устройствах пользователя](https://yandex.ru/dev/dialogs/smart-home/doc/ru/reference/get-devices.md). | Да || || devices | [Array](*array) of [objects](*object) | Массив с устройствами, которые изменили свое состояние. Массив не должен быть пустым. | Да || |#
**Объект `devices`** #| || **Параметр** | **Тип** | **Описание** | **Обязательный** || || id | [String](*string) | Идентификатор устройства. Должен быть уникален среди всех устройств производителя. | Да || || status | [String](*string) | Статус устройства. Допустимые значения: - `online`, - `offline`. Если устройство недоступно, в поле передается значение `offline`, а в приложении ![](../_images/smart-home-app.svg)[Дом с Алисой](https://alice.yandex.ru/smart-home) отобразится статус устройства «не в сети». Если пользователь настроил отправку оповещений (**Уведомления о состоянии** → **Не в сети** → **Уведомить о состоянии устройства «не в сети»**), то ему также придет пуш-уведомление об обрыве соединения. Примеры запросов при изменении статуса устройства: [переход в offline](https://yandex.ru/dev/dialogs/smart-home/doc/ru/reference-alerts/post-skill_id-callback-state.md#example-offline), [возврат в online](https://yandex.ru/dev/dialogs/smart-home/doc/ru/reference-alerts/post-skill_id-callback-state.md#example-online). | Да, если отсутствуют `capabilities` и `properties` || || capabilities | [Array](*array) of [objects](*object) | Массив с информацией о новых состояниях [умений](https://yandex.ru/dev/dialogs/smart-home/doc/ru/concepts/capability-types.md) устройств. Пустой массив изменением не считается. Если менять нечего, поле не передается. | Да, если отсутствуют `status` и `properties` || || properties | [Array](*array) of [objects](*object) | Массив с информацией о новых состояниях [свойств](https://yandex.ru/dev/dialogs/smart-home/doc/ru/concepts/properties-types.md). Пустой массив изменением не считается. Если менять нечего, поле не передается. | Да, если отсутствуют `status` и `capabilities` || |#
**Объект `capabilities`** #| || **Параметр** | **Тип** | **Описание** | **Обязательный** || || \ | [Object](*object) | Описание нового состояния умения. Подробнее со списком доступных умений и их параметрами можно ознакомиться в разделе [Об умениях](https://yandex.ru/dev/dialogs/smart-home/doc/ru/concepts/capability-types.md). Формат описания нового состояния совпадает с форматом, который используется в ответе на запрос [Информация о состояниях устройств пользователя](https://yandex.ru/dev/dialogs/smart-home/doc/ru/reference/post-devices-query.md). | Нет || || \ | [Object](*object) | Описание нового состояния умения. Подробнее со списком доступных умений и их параметрами можно ознакомиться в разделе [Об умениях](https://yandex.ru/dev/dialogs/smart-home/doc/ru/concepts/capability-types.md). Формат описания нового состояния совпадает с форматом, который используется в ответе на запрос [Информация о состояниях устройств пользователя](https://yandex.ru/dev/dialogs/smart-home/doc/ru/reference/post-devices-query.md). | Нет || |#
**Объект `properties`** #| || **Параметр** | **Тип** | **Описание** | **Обязательный** || || \ | [Object](*object) | Описание нового состояния свойства. Подробнее со списком доступных свойств и их параметрами можно ознакомиться в разделе [О свойствах](https://yandex.ru/dev/dialogs/smart-home/doc/ru/concepts/properties-types.md). Формат описания нового состояния совпадает с форматом, который используется в ответе на запрос [Информация о состояниях устройств пользователя](https://yandex.ru/dev/dialogs/smart-home/doc/ru/reference/post-devices-query.md). | Нет || || \ | [Object](*object) | Описание нового состояния свойства. Подробнее со списком доступных свойств и их параметрами можно ознакомиться в разделе [О свойствах](https://yandex.ru/dev/dialogs/smart-home/doc/ru/concepts/properties-types.md). Формат описания нового состояния совпадает с форматом, который используется в ответе на запрос [Информация о состояниях устройств пользователя](https://yandex.ru/dev/dialogs/smart-home/doc/ru/reference/post-devices-query.md). | Нет || |# #### Что должно быть в объекте `devices` {#device-required-fields} В объекте каждого устройства из массива `devices` обязательно передать хотя бы одно из: - `status` — изменение доступности устройства (`online` или `offline`); - непустой массив `capabilities` — изменение состояния умений; - непустой массив `properties` — изменение показаний свойств. Пустой массив изменением не считается. Если менять нечего, поле не передается. Допускается запрос, содержащий только `status`, — например, при потере или восстановлении связи с устройством, когда состояние умений и свойств не изменилось. {% note warning %} Для устройств, у которых в ответе на запрос [Информация об устройствах пользователя](https://yandex.ru/dev/dialogs/smart-home/doc/ru/reference/get-devices.md) указано `status_info.reportable: true`, отправка поля `status` обязательна при каждом переходе доступности — как в `offline`, так и в `online`. {% endnote %} #### Требования к `ts` {#ts-requirements} Поле `ts` содержит время возникновения события, а не время отправки уведомления. Формат — unix timestamp в секундах (дробное число). - Платформа использует `ts` для упорядочивания событий. Значение `ts` должно быть монотонным для каждого устройства: `ts` последующего события не должен быть меньше `ts` предыдущего. - Если платформа получает уведомление с устаревшим `ts` (меньшим, чем у уже обработанного события для того же устройства), такое событие игнорируется. - Не используйте `ts` для задержки отправки — событие отправляется по факту его наступления. - Часы на серверах провайдера должны быть синхронизированы. Значение `ts` из будущего приведет к тому, что последующие события будут отброшены как устаревшие. ## Формат ответа {#output-structure} {% list tabs %} - Успешный ответ ```json translate=no HTTP/1.1 202 Accepted { "request_id": String, "status": "ok" } ``` #| || **Параметр** | **Тип** | **Описание** | **Обязательный** || || request_id | [String](*string) | Идентификатор запроса. Необходимо логировать для расследования инцидентов. | Да || || status | [String](*string) | Статус обработки запроса. Допустимые значения: - `ok`. | Да || |# - Ответ с ошибкой ```json translate=no HTTP/1.1 400 { "request_id": String, "status": "error", "error_code": String, "error_message": String } ``` #| || **Параметр** | **Тип** | **Описание** | **Обязательный** || || request_id | [String](*string) | Идентификатор запроса. Необходимо логировать для расследования инцидентов. | Да || || status | [String](*string) | Статус обработки запроса. Допустимые значения: - `error`. | Да || || error_code | [String](*string) | Код ошибки. Допустимые значения: - `BAD_REQUEST`; - `UNKNOWN_USER`. | Нет || || error_message | [String](*string) | Сообщение об ошибке. | Нет || |# [Коды ошибок](https://yandex.ru/dev/dialogs/smart-home/doc/ru/concepts/responses-codes-alerts.md) {% endlist %} ## Обработка ошибок и повторные запросы {#retries} Навык должен обрабатывать ответ платформы на свой запрос в соответствии с таблицей ниже. Принятое уведомление платформа подтверждает кодом `202 Accepted`. Код `200 OK` в ответ на запрос в сервис уведомлений не возвращается. #| ||**HTTP-код** | **status** | **error_code** | **Что произошло** | **Что делать**|| ||`202 Accepted` | `ok` | — | Уведомление принято в обработку | Ничего. Повторять запрос не нужно|| ||`400` | `error` | `BAD_REQUEST` | Невалидный JSON или тело запроса не соответствует контракту: не передано ни одно из `status`, `capabilities`, `properties`; неизвестное умение или свойство; невалидное значение | Повтор запроса в неизменном виде не даст результата — он будет отклонен снова. Исправьте формирование запроса на своей стороне|| ||`400` | `error` | `UNKNOWN_USER` | Платформа не знает пользователя с таким `user_id`: аккаунты не связаны или связка разорвана | Не повторять. Остановить отправку уведомлений для этого `user_id` до следующей [связки аккаунтов](https://yandex.ru/dev/dialogs/smart-home/doc/ru/auth/when-to-use.md)|| ||`401` | — | — | Не передан или истек OAuth-токен | Обновить [OAuth-токен для Диалогов](https://yandex.ru/dev/dialogs/smart-home/doc/ru/reference-alerts/resources-alerts.md#oauth) и повторить запрос|| ||`403` | — | — | Владелец токена не является владельцем навыка | Не повторять. Использовать токен пользователя Яндекса, который создал навык|| ||`404` | — | — | В пути запроса указан неверный `skill_id` | Не повторять. Проверить идентификатор навыка|| ||`5xx`, таймаут, сетевая ошибка | — | — | Временная проблема на стороне платформы или сети | Повторить запрос с нарастающей задержкой, сохранив исходное значение `ts`|| ||`429 Too Many Requests` | — | — | Прием уведомлений от навыка ограничен — платформа считает отправку нарушающей [требования к уведомлениям](https://yandex.ru/dev/dialogs/smart-home/doc/ru/concepts/notifications-requirements.md#callback-throttling) | Остановить отправку и устранить причину ограничения. Подробнее см. в разделе [Ограничение приема уведомлений](https://yandex.ru/dev/dialogs/smart-home/doc/ru/concepts/notifications-requirements.md#callback-throttling)|| |# При повторной отправке не нужно: - повторять запрос, отклоненный с `BAD_REQUEST` или `UNKNOWN_USER`, — он будет отклонен снова; - подставлять новое значение `ts` — при повторе передается исходное время события; - отправлять уведомление об изменении, которого не было, — например, повторно отправлять последнее состояние по таймеру. Если после нескольких повторов доставить событие не удалось, отправьте актуальное состояние устройства новым уведомлением с новым `ts`, а не копию устаревшего события. ## Примеры {#example-JSON} ### Переход в offline {#example-offline} > ```bash translate=no > 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": "lamp-001", > "status": "offline" > }] > } > }' > ``` > ```json translate=no > HTTP/1.1 202 Accepted > > { > "request_id": "75442486-0878-440c-9db1-a7006c25a39f", > "status": "ok" > } > ``` ### Возврат в online {#example-online} > ```bash translate=no > 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": 1602703400.5, > "payload": { > "user_id": "provider-user-id-1", > "devices": [{ > "id": "lamp-001", > "status": "online" > }] > } > }' > ``` > ```json translate=no > HTTP/1.1 202 Accepted > > { > "request_id": "a1b2c3d4-5678-90ef-1234-567890abcdef", > "status": "ok" > } > ``` ### Изменение состояния умения {#example-capability} > ```bash translate=no > 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": 1602703500.0, > "payload": { > "user_id": "provider-user-id-1", > "devices": [{ > "id": "lamp-001", > "capabilities": [{ > "type": "devices.capabilities.on_off", > "state": { > "instance": "on", > "value": true > } > }] > }] > } > }' > ``` > ```json translate=no > HTTP/1.1 202 Accepted > > { > "request_id": "b2c3d4e5-6789-01ab-cdef-234567890abc", > "status": "ok" > } > ``` ### Изменение состояния свойства {#example-property} > ```bash translate=no > 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": 1602703600.0, > "payload": { > "user_id": "provider-user-id-1", > "devices": [{ > "id": "sensor-001-snsr", > "properties": [{ > "type": "devices.properties.event", > "state": { > "instance": "motion", > "value": "detected" > } > }] > }] > } > }' > ``` > ```json translate=no > HTTP/1.1 202 Accepted > > { > "request_id": "c3d4e5f6-7890-12ab-cdef-34567890abcd", > "status": "ok" > } > ``` ### Одновременное изменение статуса и состояния {#example-status-and-state} > ```bash translate=no > 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": 1602703700.0, > "payload": { > "user_id": "provider-user-id-1", > "devices": [{ > "id": "lamp-001", > "status": "online", > "capabilities": [{ > "type": "devices.capabilities.on_off", > "state": { > "instance": "on", > "value": true > } > }], > "properties": [{ > "type": "devices.properties.float", > "state": { > "instance": "temperature", > "value": 23.5 > } > }] > }] > } > }' > ``` > ```json translate=no > HTTP/1.1 202 Accepted > > { > "request_id": "d4e5f6a7-8901-23ab-cdef-4567890abcde", > "status": "ok" > } > ``` ### Успешный ответ — 202 Accepted {#example-success} > ```json translate=no > HTTP/1.1 202 Accepted > > { > "request_id": "75442486-0878-440c-9db1-a7006c25a39f", > "status": "ok" > } > ``` ### Ответ с ошибкой {#example-error} > ```json translate=no > HTTP/1.1 400 > > { > "request_id": "same-as-in-request", > "status": "error", > "error_code": "UNKNOWN_USER", > "error_message": "User not found" > } > ``` Как обрабатывать ответ платформы, см. в разделе [Обработка ошибок и повторные запросы](#retries). [![Служба поддержки](../_images/support-image.svg)](https://yandex.ru/dev/dialogs/smart-home/doc/ru/feedback.md) [*float]: Число с плавающей точкой с точностью до 6-9 десятичных знаков. [*string]: Cтрока, выделяется кавычками, например `"Hello world"`. [*object]: Список пар `"ключ": значение`, разделенных запятой. Выделяется фигурными скобками `{}`. ```json translate=no { "name": "John", "surname": "Smith" } ``` [*array]: Массив элементов, разделенных запятой. Элементом могут быть стандартные элементы JSON: строка, число, `true`, `false`, объект или массив. Массив выделяется квадратными скобками `[]`: ```json translate=no "cities": ["Moscow", "Tokyo", "New York"] ``` [*skill_id]: Идентификатор вызываемого навыка, присвоенный при создании. Чтобы узнать идентификатор своего навыка, откройте его в [консоли разработчика](https://dialogs.yandex.ru/developer/) — идентификатор можно скопировать на вкладке **Общие сведения**, внизу страницы.