Unit Settings API

Note: Register now for Alexa Live, Amazon’s annual Alexa developer conference on July 20, 2022.

Note: This API is only available to registered Alexa Smart Properties for hospitality partners. See Get Started with Alexa Smart Properties for Hospitality APIs.

Use the Unit API to manage unit settings for Alexa Smart Properties for hospitality units such as rooms.

Note: When you create a unit, you must set the default music provider and the default music station in order to be able to control the music experience in the unit.

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

Note: In the request header, set Host to one of the following, depending on the region of your organization: api.amazonalexa.com or api.eu.amazonalexa.com.

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

Request path parameters

Field	Description	Type	Required
`unitId`	The unit ID, in the format `"amzn1.alexa.unit.did.{id}"`.	String	Yes

Request body

None.

Response header

Note: In the response header, the returned Host value is the same as the Host value in the request.

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

Field	Description	Type	Required
`X-Amzn-RequestId`	Unique identifier for the request. If a problem occurs, Amazon can use this value to troubleshoot the problem.	String	Yes

Response body example

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

Response body parameters

Field	Description	Type	Required
`providerId`	The radio station provider ID. For supported values, see Provider and station ID reference.	String	Yes
`stationId`	The station ID. For supported values, see Provider and station ID reference.	String	Yes

Error response

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

Error response parameters

Field	Description	Type	Required
`type`	The error type.	String	No
`message`	The error message for the error. Note: The error message appears only for debugging/logging purposes. You must not share it with the customer. No business logic should depend on the content of the error message.	String	No

HTTP response codes

Status Code	Name	Description
200	OK	The request succeeded.
204	No content	The setting exists, but it doesn't have a value.
401	Unauthorized	The access token is missing, expired, or invalid.
403	Forbidden	The user doesn't have permission to perform the operation.
429	Too many requests	The request is throttled.

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

Note: In the request header, set Host to one of the following, depending on the region of your organization: api.amazonalexa.com or api.eu.amazonalexa.com.

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

Request path parameters

Field	Description	Type	Required
`unitId`	The unit ID, in the format `"amzn1.alexa.unit.did.{id}"`.	String	Yes

Request body example

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

Request body parameters

Field	Description	Type	Required
`providerId`	The radio station provider ID. For supported values, see Provider and station ID reference.	String	Yes
`stationId`	The station ID. For supported values, see Provider and station ID reference.	String	Yes

Response header

Note: In the response header, the returned Host value is the same as the Host value in the request.

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

Field	Description	Type	Required
`X-Amzn-RequestId`	Unique identifier for the request. If a problem occurs, Amazon can use this value to troubleshoot the problem.	String	Yes

Response body

None.

Error response

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

Error response parameters

Field	Description	Type	Required
`type`	The error type.	String	No
`message`	The error message for the error. Note: The error message appears only for debugging/logging purposes. You must not share it with the customer. No business logic should depend on the content of the error message.	String	No

HTTP response codes

Status Code	Name	Description
204	No content	Setting applied.
400	Bad Request	The request is malformed or is missing one or more required parameters.
403	Forbidden	The user doesn't have permission to perform the operation.
429	Too many requests	The request is throttled.

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.

Note: This request isn't supported in the UK (en-GB) or France (fr-FR).

Request format

Note: In the request header, set Host to one of the following, depending on the region of your organization: api.amazonalexa.com or api.eu.amazonalexa.com.

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

Request body

None.

Request parameters

Field	Description	Type	Required
`unitId`	The unit ID, in the format `"amzn1.alexa.unit.did.{id}"`.	String	Yes

Response header

Note: In the response header, the returned Host value is the same as the Host value in the request.

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

Field	Description	Type	Required
`X-Amzn-RequestId`	Unique identifier for the request. If a problem occurs, Amazon can use this value to troubleshoot the problem.	String	Yes

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

Field	Description	Type	Required
`code`	The error name, for example, `DEVICE_UNREACHABLE`.	String	No
`endpointId`	The endpoint ID, in the Amazon Common Identifier (ACI) format `"amzn1.alexa.endpoint.{id}"`.	String	No
`description`	The error message for the error. Note: The error message appears only for debugging/logging purposes. You must not share it with the customer. No business logic should depend on the content of the error message.	String	No

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

Status Code	Name	Description
204	No content	Alarms were successfully deleted on all endpoints in the unit. Note that this status code is returned even if the unit has no alarms to delete.
400	BAD_REQUEST	The request is malformed or is missing one or more required parameters.
401	UNAUTHORIZED	The authentication token is invalid or doesn't have access to the resource.
401	FORBIDDEN	The user doesn't have permission to perform the operation, or the unit doesn't exist.
500	INTERNAL_SERVER_ERROR	The request couldn't be handled because of an internal service error.
504	DEVICE_NOT_REACHABLE	The device is offline or unreachable.

Provider and station ID reference

The following table lists the supported providerId and stationId values. Country/region string is in ISO 3166-1 alpha-2 format.

Country/Region String	Provider ID	Station ID	Description
US	I_HEART_RADIO	4802	American Top 40
US	I_HEART_RADIO	4426	Classic Rock (IHR_CLASSIC_ROCK)
US	I_HEART_RADIO	4429	Hip Hop (IHR_HIPHOP)
US	I_HEART_RADIO	4422	Pop (IHR_POP)
US	I_HEART_RADIO	4418	Country (IHR_COUNTRY)
US	I_HEART_RADIO	7193	Latin (IHR_LATIN)
US	I_HEART_RADIO	5953	Dance (IHR_DANCE)
US	I_HEART_RADIO	5162	Gospel (IHR_GOSPEL)
US	I_HEART_RADIO	4242	Jazz (IHR_JAZZ)
US	I_HEART_RADIO	6377	Classical (IHR_CLASSICAL)
US	I_HEART_RADIO	4409	Mix (IHR_MIX)
US	I_HEART_RADIO	4717	Oldies (IHR_OLDIES)
US	I_HEART_RADIO	4447	Alternative (IHR_ALTERNATIVE)
US	I_HEART_RADIO	7312	Wynn's Station (IHR_WYNN_MUSIC)
UK	TUNEIN	s45300	Jazz (TSF Jazz)
UK	TUNEIN	s287575	Relaxing ( The Relaxing Radio Show)
UK	TUNEIN	s266086	Meditation (Ambi Nature Radio)
UK	TUNEIN	s243906	MPR Classical Lullabies
UK	GLOBAL_PLAYER	7946cba4-3a8c-424a-a2e5-e555bb8a09a3	Pop (Smooth Thames Valley)
UK	GLOBAL_PLAYER	c374b219-8b87-4c9f-aade-4704727b48bd	Great Hits (from Gold)
UK	GLOBAL_PLAYER	66a602fa-f80a-4c2f-9fab-26bb436c7376	Country (Smooth Country)
UK	GLOBAL_PLAYER	789e024c-6c90-4793-a54b-fd6be69d5274	Classical (Classic FM)
UK	GLOBAL_PLAYER	eee30e01-9a26-4e82-81a2-45012648baa3	Rock ( Radio X London)
UK	GLOBAL_PLAYER	5b08094f-59fa-41ba-8e81-78f0ad0b26db	Dance (Heart Dance)
UK	GLOBAL_PLAYER	5af71b40-104e-45ac-8940-c99418a5bafe	Heart (Heart London)
FR	TUNEIN	s16492	Jazz (TSF Jazz)
FR	TUNEIN	s287575	Relaxing (The Relaxing Radio Show)
FR	TUNEIN	s298983	Smooth Jazz (Crooner Radio Lounge)
FR	TUNEIN	s178199	Pop (Pop Gold)
FR	TUNEIN	s196675	Country (Chris country FM)
FR	TUNEIN	s107537	Classical 102
FR	TUNEIN	s257854	Relaxing
FR	TUNEIN	s266086	Meditation (Ambi Nature Radio)
FR	TUNEIN	s54693	MPR Classical Lullabies