Notification about device parameter change

Notifies Yango Smart Home about the changed device parameters.

Example situation when the current request is sent: the skill developer updated the list of capabilities for the user device or the user renamed the device in the provider's app.

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 dialogs.yango.com/api/v1/skills/{skill_id}/callback/discovery

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": Float64,
    "payload": {
        "user_id": String
    }
}


Parameter	Type	Description	Required
`ts`	Float64	Time of the event in seconds and fractions of a second (UNIX timestamp format). For example, the value `1611764267.120` corresponds to January 27, 2021 16 hours 17 minutes 47 seconds 120 milliseconds.	Yes
`payload`	Object	Object with ID.	Yes
`payload` object
`user_id`	String	User identifier sent in response to the Information about user devices request.	Yes


Parameter	Type	Description	Required
`ts`	Float64	Time of the event in seconds and fractions of a second (UNIX timestamp format). For example, the value `1611764267.120` corresponds to January 27, 2021 16 hours 17 minutes 47 seconds 120 milliseconds.	Yes
`payload`	Object	Object with ID.	Yes
`payload` object
`user_id`	String	User identifier sent in response to the Information about user devices request.	Yes

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

HTTP/1.1 400

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


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: `error`.	Yes
`error_code`	String	Error code. Acceptable values: `BAD_REQUEST` `UNKNOWN_USER`.	No
`error_message`	String	Error message.	No


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: `error`.	Yes
`error_code`	String	Error code. Acceptable values: `BAD_REQUEST` `UNKNOWN_USER`.	No
`error_message`	String	Error message.	No

Error codes

Example

curl -i -X POST 'https://dialogs.yango.com/api/v1/skills/user-test-skill/callback/discovery' \
-H 'Authorization: OAuth 123qwe456a...' \
-H 'Content-Type: application/json' \
-d '{
    "ts": 1611764267.120,
    "payload": {
        "user_id": "provider-user-id-1"
    }
}'

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