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

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

Request body

None.

Response header

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

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

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.

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

Field Description Type Required

unitId

The unit ID, in the format "amzn1.alexa.unit.did.{id}".

String

Yes

Response header

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