---
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/en/reference-alerts/post-skill_id-callback-state.md
    type: text/markdown
    title: Markdown version
  - href: https://yandex.ru/dev/dialogs/smart-home/doc/en/llms.txt?revision=r21995741
    rel: describedby
---
> **Documentation Index:** Fetch the complete configuration index at https://yandex.ru/dev/dialogs/smart-home/doc/en/llms.txt?revision=r21995741

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

<!-- source: en/_includes/reference-alerts/resources-alerts/id-resources-alerts/reference-alerts-test-in-private.md -->
{% note info %}

The notification service is available only for published skills. If your skill is still under development, you can make it private for the  [testing](https://yandex.ru/dev/dialogs/smart-home/doc/en/testing.md) period so that external users can't access it.

{% endnote %}
<!-- endsource: en/_includes/reference-alerts/resources-alerts/id-resources-alerts/reference-alerts-test-in-private.md -->


## Request format {#input}

```
POST https://dialogs.yandex.net/api/v1/skills/{[skill_id](*skill_id)}/callback/state
```


#### Request headers {#headers}

#|
||
**Parameter**
|
**Description**
|
**Required**
||

||
<!-- source: en/_includes/reference/struct-table-protocol/id-struct-table-protocol/auth-row-col-1.md -->
Authorization
<!-- endsource: en/_includes/reference/struct-table-protocol/id-struct-table-protocol/auth-row-col-1.md -->
|
<!-- source: en/_includes/reference/struct-table-protocol/id-struct-table-protocol/auth-row-col-2.md -->
Authorization [token of the skill owner](https://yandex.ru/dev/dialogs/smart-home/doc/en/reference-alerts/resources-alerts.md#oauth).
<!-- endsource: en/_includes/reference/struct-table-protocol/id-struct-table-protocol/auth-row-col-2.md -->
|
<!-- source: en/_includes/reference/struct-table-protocol/id-struct-table-protocol/auth-row-col-3.md -->
Yes
<!-- endsource: en/_includes/reference/struct-table-protocol/id-struct-table-protocol/auth-row-col-3.md -->
||

||
<!-- source: en/_includes/reference/struct-table-protocol/id-struct-table-protocol/content-type-row-col-1.md -->
Content-Type
<!-- endsource: en/_includes/reference/struct-table-protocol/id-struct-table-protocol/content-type-row-col-1.md -->
|
<!-- source: en/_includes/reference/struct-table-protocol/id-struct-table-protocol/content-type-row-col-2.md -->
The format of sent/submitted data. Possible values: application/json.
<!-- endsource: en/_includes/reference/struct-table-protocol/id-struct-table-protocol/content-type-row-col-2.md -->
|
<!-- source: en/_includes/reference/struct-table-protocol/id-struct-table-protocol/content-type-row-col-3.md -->
Yes, in operations with HTTP POST
<!-- endsource: en/_includes/reference/struct-table-protocol/id-struct-table-protocol/content-type-row-col-3.md -->
||
|#


#### Request body format {#structure-in}

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

<!-- source: en/_includes/reference-alerts/struct-table-protocol-alerts/id-struct-table-protocol-alerts/post-skill_id-callback-state-request.md -->
#|
||
**Parameter**
|
**Type**
|
**Description**
|
**Required**
||

||
ts
|
[Float](*float)
|
Time of the event in seconds (UNIX timestamp format).
|
Yes
||

||
<!-- source: en/_includes/reference/struct-table-protocol/id-struct-table-protocol/payload-col-1.md -->
payload
<!-- endsource: en/_includes/reference/struct-table-protocol/id-struct-table-protocol/payload-col-1.md -->
|
<!-- source: en/_includes/reference/struct-table-protocol/id-struct-table-protocol/payload-col-2.md -->
[Object](*object)
<!-- endsource: en/_includes/reference/struct-table-protocol/id-struct-table-protocol/payload-col-2.md -->
|
<!-- source: en/_includes/reference/struct-table-protocol/id-struct-table-protocol/payload-col-3.md -->
Object with devices.
<!-- endsource: en/_includes/reference/struct-table-protocol/id-struct-table-protocol/payload-col-3.md -->
|
<!-- source: en/_includes/reference/struct-table-protocol/id-struct-table-protocol/payload-col-4.md -->
Yes
<!-- endsource: en/_includes/reference/struct-table-protocol/id-struct-table-protocol/payload-col-4.md -->
||
|#

<br>

**`payload` object**

#|
||
**Parameter**
|
**Type**
|
**Description**
|
**Required**
||

||
user_id
|
[String](*string)
|
User identifier sent in response to the [Information about user devices](https://yandex.ru/dev/dialogs/smart-home/doc/en/reference/get-devices.md) request.
|
Yes
||

||
devices
|
[Array](*array) of [objects](*object)
|
Array of the devices that changed their state.
|
Yes
||
|#

<br>


**`devices` object**

#|
||
**Parameter**
|
**Type**
|
**Description**
|
**Required**
||

||
<!-- source: en/_includes/reference/struct-table-protocol/id-struct-table-protocol/device-id-row-col-1.md -->
id
<!-- endsource: en/_includes/reference/struct-table-protocol/id-struct-table-protocol/device-id-row-col-1.md -->
|
<!-- source: en/_includes/reference/struct-table-protocol/id-struct-table-protocol/device-id-row-col-2.md -->
[String](*string)
<!-- endsource: en/_includes/reference/struct-table-protocol/id-struct-table-protocol/device-id-row-col-2.md -->
|
<!-- source: en/_includes/reference/struct-table-protocol/id-struct-table-protocol/device-id-row-col-3.md -->
Device ID. It must be unique among all the manufacturer's devices.
<!-- endsource: en/_includes/reference/struct-table-protocol/id-struct-table-protocol/device-id-row-col-3.md -->
|
<!-- source: en/_includes/reference/struct-table-protocol/id-struct-table-protocol/device-id-row-col-4.md -->
Yes
<!-- endsource: en/_includes/reference/struct-table-protocol/id-struct-table-protocol/device-id-row-col-4.md -->
||


||
<!-- source: en/_includes/reference/struct-table-protocol/id-struct-table-protocol/device-status-row-col-1.md -->
status
<!-- endsource: en/_includes/reference/struct-table-protocol/id-struct-table-protocol/device-status-row-col-1.md -->
|
<!-- source: en/_includes/reference/struct-table-protocol/id-struct-table-protocol/device-status-row-col-2.md -->
[String](*string)
<!-- endsource: en/_includes/reference/struct-table-protocol/id-struct-table-protocol/device-status-row-col-2.md -->
|
<!-- source: en/_includes/reference/struct-table-protocol/id-struct-table-protocol/device-status-row-col-3.md -->
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 ![](../_images/smart-home-app.svg)[Home with Alice](https://alice.yandex.ru/smart-home) 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](https://yandex.ru/dev/dialogs/smart-home/doc/en/reference-alerts/post-skill_id-callback-state.md#status-request).
<!-- endsource: en/_includes/reference/struct-table-protocol/id-struct-table-protocol/device-status-row-col-3.md -->
|
<!-- source: en/_includes/reference/struct-table-protocol/id-struct-table-protocol/device-status-row-col-4.md -->
No
<!-- endsource: en/_includes/reference/struct-table-protocol/id-struct-table-protocol/device-status-row-col-4.md -->
||

||
capabilities
|
[Array](*array) of [objects](*object)
|
Array with information about the new states of [capabilities](https://yandex.ru/dev/dialogs/smart-home/doc/en/concepts/capability-types.md) of the devices.
|
Yes, if the `properties` parameter is omitted
||

||
properties
|
[Array](*array) of [objects](*object)
|
Array with information about the new states of [properties](https://yandex.ru/dev/dialogs/smart-home/doc/en/concepts/properties-types.md).
|
Yes, if the `capabilities` parameter is omitted
||
|#

<br>


**`capabilities` object**

#|
||
**Parameter**
|
**Type**
|
**Description**
|
**Required**
||

||
\<capability1>
|
[Object](*object)
|
<!-- source: en/_includes/reference-alerts/struct-table-protocol-alerts/id-struct-table-protocol-alerts/capability-ph-description-post-skill_id-callback-state.md -->
Describing a new capability state. For more information about the list of available capabilities and their parameters, see [About capabilities](https://yandex.ru/dev/dialogs/smart-home/doc/en/concepts/capability-types.md). The format for describing a new state is the same as used in the response to the [Information about the states of user devices](https://yandex.ru/dev/dialogs/smart-home/doc/en/reference/post-devices-query.md).
<!-- endsource: en/_includes/reference-alerts/struct-table-protocol-alerts/id-struct-table-protocol-alerts/capability-ph-description-post-skill_id-callback-state.md -->
|
No
||

||
\<capability2>
|
[Object](*object)
|
<!-- source: en/_includes/reference-alerts/struct-table-protocol-alerts/id-struct-table-protocol-alerts/capability-ph-description-post-skill_id-callback-state.md -->
Describing a new capability state. For more information about the list of available capabilities and their parameters, see [About capabilities](https://yandex.ru/dev/dialogs/smart-home/doc/en/concepts/capability-types.md). The format for describing a new state is the same as used in the response to the [Information about the states of user devices](https://yandex.ru/dev/dialogs/smart-home/doc/en/reference/post-devices-query.md).
<!-- endsource: en/_includes/reference-alerts/struct-table-protocol-alerts/id-struct-table-protocol-alerts/capability-ph-description-post-skill_id-callback-state.md -->
|
No
||
|#

<br>


**`properties` object**

#|
||
**Parameter**
|
**Type**
|
**Description**
|
**Required**
||

||
\<property1>
|
[Object](*object)
|
<!-- source: en/_includes/reference-alerts/struct-table-protocol-alerts/id-struct-table-protocol-alerts/property-ph-description-post-skill_id-callback-state.md -->
Description of the new property state. For more information about the list of available properties and their parameters, see [About properties](https://yandex.ru/dev/dialogs/smart-home/doc/en/concepts/properties-types.md). The format for describing a new state is the same as used in the response to the [Information about the states of user devices](https://yandex.ru/dev/dialogs/smart-home/doc/en/reference/post-devices-query.md).
<!-- endsource: en/_includes/reference-alerts/struct-table-protocol-alerts/id-struct-table-protocol-alerts/property-ph-description-post-skill_id-callback-state.md -->
|
No
||

||
\<property2>
|
[Object](*object)
|
<!-- source: en/_includes/reference-alerts/struct-table-protocol-alerts/id-struct-table-protocol-alerts/property-ph-description-post-skill_id-callback-state.md -->
Description of the new property state. For more information about the list of available properties and their parameters, see [About properties](https://yandex.ru/dev/dialogs/smart-home/doc/en/concepts/properties-types.md). The format for describing a new state is the same as used in the response to the [Information about the states of user devices](https://yandex.ru/dev/dialogs/smart-home/doc/en/reference/post-devices-query.md).
<!-- endsource: en/_includes/reference-alerts/struct-table-protocol-alerts/id-struct-table-protocol-alerts/property-ph-description-post-skill_id-callback-state.md -->
|
No
||
|#
<!-- endsource: en/_includes/reference-alerts/struct-table-protocol-alerts/id-struct-table-protocol-alerts/post-skill_id-callback-state-request.md -->

#### Example of a request when the device status changes {#status-request}

> ```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": "sensor-001-snsr",
>       "status": "offline"
>     }]
>   }
> }'
> ```

## Response format {#output-structure}


{% list tabs %}

- Response successful


  ```json translate=no
  HTTP/1.1 202 Accepted

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

  <!-- source: en/_includes/reference-alerts/struct-table-protocol-alerts/id-struct-table-protocol-alerts/post-skill_id-callback-state-response.md -->
  #|
  ||
  **Parameter**
  |
  **Type**
  |
  **Description**
  |
  **Required**
  ||

  ||
  request_id
  |
  [String](*string)
  |
  Request ID. Must be logged for the purpose of incident investigation.
  |
  Yes
  ||

  ||
  status
  |
  [String](*string)
  |
  Status of processing the request. Acceptable values:
  - `ok`.
  |
  Yes
  ||
  |#
  <!-- endsource: en/_includes/reference-alerts/struct-table-protocol-alerts/id-struct-table-protocol-alerts/post-skill_id-callback-state-response.md -->



- Response with error


  ```json translate=no
  HTTP/1.1 400

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

  <!-- source: en/_includes/reference-alerts/struct-table-protocol-alerts/id-struct-table-protocol-alerts/post-skill_id-callback-state-response-error.md -->
  <!-- Response error -->


  #|
  ||
  **Parameter**
  |
  **Type**
  |
  **Description**
  |
  **Required**
  ||

  ||
  request_id
  |
  [String](*string)
  |
  Request ID. Must be logged for the purpose of incident investigation.
  |
  Yes
  ||

  ||
  status
  |
  [String](*string)
  |
  Status of processing the request. Acceptable values:
    - `error`.

  |
  Yes
  ||

  ||
  error_code
  |
  [String](*string)
  |
  Error code. Acceptable values:
  - `BAD_REQUEST`;
  - `UNKNOWN_USER`.
  |
  No
  ||

  ||
  error_message
  |
  [String](*string)
  |
  Error message.
  |
  No
  ||
  |#
  <!-- endsource: en/_includes/reference-alerts/struct-table-protocol-alerts/id-struct-table-protocol-alerts/post-skill_id-callback-state-response-error.md -->


  [Error codes](https://yandex.ru/dev/dialogs/smart-home/doc/en/concepts/responses-codes-alerts.md)

{% endlist %}


## Example {#example-JSON}

> {% list tabs %}
>
> - Request
>
>
>   ```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": "sensor-001-snsr",
>               "capabilities": [],
>               "properties": [{
>                   "type": "devices.properties.event",
>                   "state": {
>                       "instance": "motion",
>                       "value": "detected"
>                   }
>               }]
>           }]
>       }
>   }'
>   ```
>
>
> - Response successful
>
>
>   ```json translate=no
>   HTTP/1.1 202 Accepted
>
>   {
>     "request_id": "75442486-0878-440c-9db1-a7006c25a39f",
>     "status": "ok"
>   }
>   ```
>
>
> - Response with 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"
>   }
>   ```
>
> {% endlist %}


<!-- {% include [support-support-button](../_includes/about/id-support/support-button.md) %}-->

[*float]:
  Floating-point number with a precision of 6-9 decimal digits.

[*string]:
  String enclosed in quotation marks, for example: `"Hello, world"`.

[*object]:
  List of `"key": value` pairs separated by commas. The list is enclosed in curly brackets `{}`.

```json translate=no
{
  "name": "John",
  "surname": "Smith"
}
```

[*array]:
  An array of elements separated by a comma. As array items, you can use standard JSON elements: a string, number, `true`, `false`, object, or array. Arrays are enclosed in square brackets `[]`:

```json translate=no
"cities": ["Moscow", "Tokyo", "New York"]
```

[*skill_id]:
  ID of the skill invoked (assigned at creation).

To find out your skill ID, open the skill in the [developer console](https://dialogs.yandex.ru/developer/): you can copy the skill ID in the **General information** tab at the bottom of the page.