Unit Settings API

Use the Unit API to manage unit settings for Alexa for Hospitality units such as rooms.

Get the default music station setting

Call GET /v2/units/{unitId}/settings/MusicExperience.defaultStationPreferences to get the default music station preferences for a given unit.

Request format

GET /v2/units/{unitId}/settings/MusicExperience.defaultStationPreferences HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}

Request path parameters

Request body

None.

Response header

Host: api.amazonalexa.com
X-Amzn-RequestId: {request-id}
Content-Type: application/json

Response body example

{
  "providerId": "I_HEART_RADIO",
  "stationId": "4802"
}

Response body parameters

Error response

HTTP/1.1 {ErrorCode}
{
    "type": "{ErrorType}",
    "message": "{ErrorMessage}"
}

Error response parameters

HTTP response codes

Set the default music station setting

Call PUT /v2/units/{unitId}/settings/MusicExperience.defaultStationPreferences to set the default music station preferences for a given unit.

Request format

PUT /v2/units/{unitId}/settings/MusicExperience.defaultStationPreferences HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {LWA Token}

Request path parameters

Request body example

{
  "providerId": "I_HEART_RADIO",
  "stationId": "4802"
}

Request body parameters

Response header

Host: api.amazonalexa.com
X-Amzn-RequestId: {request-id}
Content-Type: application/json

Response body

None.

Error response

HTTP/1.1 {ErrorCode}
{
    "type": "{ErrorType}",
    "message": "{ErrorMessage}"
}

Error response parameters

HTTP response codes

Delete all alarms for a unit

Call DELETE /v1/alerts/alarms?unitId={unitId} to delete all alarms on all endpoints in a unit. This API call is an extension of the AVS Alarms REST API.

Request format

DELETE /v1/alerts/alarms?unitId={unitId} HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: {LWA Token}

Request body

None.

Request parameters

Response header

Host: api.amazonalexa.com
X-Amzn-RequestId: {request-id}
Content-Type: application/json

Response

Upon successful deletion, the server returns an HTTP 204 No Content status response. A successful payload does not contain a body.

HTTP/1.1 204 No Content
Date: Thu, 22 Feb 2018 12:22:40 GMT
Content-Type: application/json

Error response

HTTP/1.1 {ErrorCode}
Content-Type: application/json

{
    "errors": [{
        "code": "{Code}",
        "endpointId": "{EndpointId}",
        "description": "{ErrorMessage}"
    }]
}

Error response parameters

Error handling for multiple device failure

If there is an error on a particular device in the unit, the API records the failure and continues deleting alarms on the remaining devices. The response returns the endpoint ID and reason for each device failure, as shown in the following example.

• If there are multiple failures with the same failure reason, the response returns the most accurate HTTP status code (for example, 504 DEVICE_NOT_REACHABLE if all failures are because of unreachable devices).
• If there are multiple failures with different failure reasons, the response returns the 500 INTERNAL_SERVER_ERROR status code, with more specific details for each failure listed in the array of errors.

HTTP/1.1 500 INTERNAL_SERVER_ERROR
Content-Type: application/json

{
    "errors": [{
            "code": "DEVICE_NOT_REACHABLE",
            "endpointId": "{ENDPOINT_ID_1}",
            "description": "Device not reachable / offline"
        },
        {
            "code": "INTERNAL_SERVER_ERROR",
            "endpointId": "{ENDPOINT_ID_2}",
            "description": "Unexpected Error"
        }
    ]
}

HTTP response codes