Communications REST API Reference

Note: Sign in to the developer console to build or publish your skill.

Note: This API is only available to registered Alexa Smart Properties partners. For details, see Get Started with Alexa Smart Properties APIs.

Use the Alexa Communications REST API to create and manage communication profiles for rooms in Alexa Smart Properties (ASP). Use these profiles to enable calling with Alexa-enabled devices between rooms on a property. For more details about the calling add-ons, see Calling with Alexa Smart Properties.

You use the communication profile instead of a unit ID to identify the Alexa-enabled devices in the room. After you create a communication profile for a room, you can add it as a contact in the address book of a different room. For more details, see Address Book REST API Reference.

API endpoint

Based on the country of your organization, set the Host parameter in the request header to one of the following API endpoints.

Country	Endpoint
CA, US	`https://api.amazonalexa.com`
DE, ES, FR, IT, UK	`https://api.eu.amazonalexa.com`
JP	`https://api.fe.amazonalexa.com`

Authentication

Each API request must have an authorization header whose value is the access token retrieved from Login with Amazon (LWA). For details, see Manage API Access.

Operations

The Communications API supports the following types of operations:

Manage communication profiles – To support calling, you must create a communications profile for each unit.
Manage calling settings – Set drop-in preferences for each unit and communication profile and define blocking rules to disable calling between two property units.

Important: The drop-in feature is only available for properties that have an Alexa Smart Properties in Healthcare subscription.

Manage communication profiles

Operation	HTTP Method and URI
Create communication profile	`POST /v1/communications/profile`
Create communication profiles in bulk	`POST /v1/communications/profiles/batch`
Delete communication profile	`DELETE /v1/communications/profile/{profileId}`
Get communication profile	`GET /v1/communications/profile/{profileId}`
Get communication profile by entity	`GET /v1/communications/profile?entity.type={type}&entity.id={id}`
Update communication profile	`PUT /v1/communications/profile/{profileId}`
Create reciprocal association	`POST /v1/communications/profile/{profileId}/reciprocalAssociations`
Delete reciprocal association	`DELETE /v1/communications/profile/{profileId}/reciprocalAssociations?contactId={contactId}`
Get reciprocal associations	`GET /v1/communications/profile/{profileId}/reciprocalAssociations?contactId={contactId}&maxResults={maxResults}&nextToken={nextToken}`

Manage calling settings

Operation	HTTP Method and URI
Create blocking rule	`PUT /v1/communications/profile/{profileId}/contacts/settings/Block?alexaCommunicationProfileId={alexaCommunicationProfileId}`
Get blocking rule settings	`GET /v1/communications/profile/{profileId}/contacts/settings/Block?value={value}`
Get drop-in settings	`GET /v1/communications/profile/{sourceProfileId}/contacts/settings/DropIn?alexaCommunicationProfileId={alexaCommunicationProfileId}`
Set drop-in preference	`PUT /v1/communications/profile/{sourceProfileId}/contacts/settings/DropIn?alexaCommunicationProfileId={alexaCommunicationProfileId}`

Create communication profile

Create a communication profile to support calling in a unit. The response includes a unique identifier, called a profileId, for the unit. You can add the profileId as a contact in the address book of a different unit.

Optionally, you can provide a name for the profile, which appears as a display name for the unit. When the guest in this unit makes a call, the name displays on the contact's Alexa-enabled devices and Alexa app. To enable guests in other units to place an inbound call to this unit, add the name for the unit to the address book of other units. If a profile for the unit already exists, the operation returns the existing profileId for the unit and updates the profile name, if different from the existing name.

Tip: To set up inbound calling, you must include a profile name. Otherwise, Alexa displays Guest as the default profile display name for the unit.

This operation is available in the following countries.

Healthcare	Hospitality	Senior Living	Core
US	US, UK, FR, CA, IT, DE, ES, JP	US, UK, FR, CA, IT, DE, ES, JP	US

Request

To create a profile, you make a POST request to the /v1/communications/profile resource.

Request path and header example

Copied to clipboard.

POST /v1/communications/profile HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {access token}

Request path and header parameters

Parameter	Located in	Description	Type	Required
`access token`	Header	Access token for the customer. Set to an LWA token.	String	Yes

Request body example

Copied to clipboard.

{
    "entity": {
        "type": "UNIT",
        "id": "amzn1.alexa.unit.did.101"
    },
    "name": "Room 101"
}

Request body properties

Property	Description	Type	Required
`entity`	Entity, such as the unit, for which to create the communications profile.	Object	Yes
`entity.type`	Type of entity. Valid value: `UNIT`.	String	Yes
`entity.id`	Identifies the unit. Formatted as an Amazon Common Identifier (ACI), `amzn1.alexa.unit.did.{id}` .	String	Yes
`name`	Display name for the communication profile. Valid value: 1–50 Unicode (UTF-8) characters that meet the following rules: Characters must be numbers, letters (Chinese characters and non-Roman letters allowed), spaces, apostrophes, dashes, or underscores. Other special characters aren't permitted. Names must contain at least one number or letter.	String	No

Response

A successful response returns HTTP 200 OK, along with the communication profile ID. On error, the response returns the appropriate HTTP status code and includes a response body with a message string that describes the error.

Tip: Use the profileId value for the alexaCommunicationsProfileId in Manage contact operations.

Response body example

{
    "entity": {
        "type": "UNIT",
        "id": "amzn1.alexa.unit.did.101"
    },
    "profileId": {
        "profileId": "amzn1.alexa.communications.profile.did.1234"
    }
}

Response body properties

Property	Description	Type
`entity`	Entity, such as the unit, for which to create the communications profile.	Object
`entity.type`	Type of entity. Valid value: `UNIT`.	String
`entity.id`	Identifies the unit. Formatted as an Amazon Common Identifier (ACI), `amzn1.alexa.unit.did.{id}`.	String
`profileId`	New communications profile for the unit.	Object
`profileId.profileId`	Uniquely identifies the communication profile. If a communication profile already exists for the specified unit, this value is the existing `profileId`. Formatted as an Amazon Common Identifier (ACI), `amzn1.alexa.communications.profile.did.{id}`.	String

HTTP status codes

Status	Description
`200 OK`	Response body contains a communication profile ID for the specified entity.
`400 Bad Request`	Indicates that one or more properties in the request body aren't valid. The request wasn't valid for one of the following reasons: `UnitId` is not valid. Please check your Input. `ProfileId` is not valid. `Name` is not valid.
`401 Unauthorized`	Request didn't include the authorization token, or the included token expired or isn't valid. Or, you don't have access to the resource.
`403 Forbidden`	Indicates that the authorization token is valid, but the requested operation isn't allowed.
`404 Not Found`	Requested resource not found.
`429 Too Many Requests`	Permitted rate limit, specified as the number of requests per unit of time, exceeded. You can retry the request by using exponential back-off.
`500 Server Error`	Error occurred on the server. You can retry the request by using exponential back-off.
`503 Service Unavailable`	Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request.

Create communication profiles in bulk

Create communication profiles for up to 100 units in a single request. Each unit receives a unique profileId. You can add the profileId as a contact in the address book of a different unit.

Tip: To set up inbound calling, you must include a profile name. Otherwise, Alexa displays Guest as the default profile display name for the unit.

This operation is available in the following countries.

Healthcare	Hospitality	Senior Living	Core
US	US, UK, FR, CA, IT, DE, ES, JP	US, UK, FR, CA, IT, DE, ES, JP	US

Request

To create profiles, you make a POST request to the /v1/communications/profiles/batch resource.

Request path and header example

Copied to clipboard.

POST /v1/communications/profiles/batch HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {access token}

Request path and header parameters

Parameter	Located in	Description	Type	Required
`access token`	Header	Access token for the customer. Set to an LWA token.	String	Yes

Request body example

Copied to clipboard.

{
    "items": [{
            "itemId": 1,
            "entity": {
                "type": "UNIT",
                "id": "amzn1.alexa.unit.did.201"
            },
            "name": "Room 201"
        },
        {
            "itemId": 2,
            "entity": {
                "type": "UNIT",
                "id": "amzn1.alexa.unit.did.202"
            },
            "name": "Room 202"
        }
    ]
}

Request body properties

Property	Description	Type	Required
`items`	List of units to which to assign a communication profile.	Array of objects	Yes
`items[].itemId`	Unique identifier for the assignment.	Integer	Yes
`items[].entity`	Entity, such as the unit, for which to create the communications profile.	Object	Yes
`items[].entity.type`	Type of entity. Valid value: `UNIT`.	String	Yes
`items[].entity.id`	Identifies the unit. Formatted as an Amazon Common Identifier (ACI), `amzn1.alexa.unit.did.{id}` .	String	Yes
`items[].name`	Display name for the communication profile. Valid value: 1–50 Unicode (UTF-8) characters that meet the following rules: Characters must be numbers, letters (Chinese characters and non-Roman letters allowed), spaces, apostrophes, dashes, or underscores. Other special characters aren't permitted. Names must contain at least one number or letter.	String	No

Response

A successful response returns HTTP 200 OK, along with a list of communication profile IDs. For overall request failure, the response returns the appropriate HTTP status code and includes a response body with a message string that describes the error. If errors occur for individual items, the response body includes the success and error items.

Tip: Use the profileId value for the alexaCommunicationsProfileId in Manage contact operations.

Response body examples

The following example shows a successful response with profile IDs assigned to each unit.

The following example shows a response body with both success and error message at the individual item level. Both results and errors properties can coexist in the same response.

The following example shows a response body with all items failed.

The following example shows an error response body for an entire request, not for individual items.

Response body properties

Property	Description	Type
`results`	List of success results.	Array of objects
`results[].itemId`	(Optional) Unique identifier from the request. Use to associate the request item with the response item. Not included if the error is at the request level.	Integer
`results[].entity`	Entity, such as the unit, for which the profile is created.	Object
`results[].entity.type`	Type of entity. Valid value: `UNIT`.	String
`results[].entity.id`	Identifies the unit. Formatted as an Amazon Common Identifier (ACI), `amzn1.alexa.unit.did.{id}` .	String
`results[].profileId`	Uniquely identifies the communication profile. If a communication profile already exists for the specified unit, this value is the existing `profileId`. Formatted as an Amazon Common Identifier (ACI), `amzn1.alexa.communications.profile.did.{id}`.	String
`errors`	(Optional) List of error results. For details about possible the error property values, see Error property values for individual items.	Array of objects
`errors[].itemId`	(Optional) Unique identifier from the request. Use to associate the request item with the response item.	Integer
`errors[].status`	HTTP response code for the failed request item.	Integer
`errors[].errorCode`	Type of error that occurred.	String
`errors[].errorDescription`	Human-readable error message. The error message appears only for debugging and logging purposes. You must not share it with the customer. No business logic should depend on the content of the error description.	String

Error property values for individual items

`status`	`errorCode`	`errorDescription`
`400`	`INVALID_PARAM`	UnitId is not valid. Please check your Input.
`400`	`INVALID_PARAM`	Given `entityType` in request is not supported. Currently the interface supports UNIT `entityType`.
`400`	`INVALID_PARAM`	Entity is mandatory.
`400`	`INVALID_PARAM`	EntityType must be between 1 and 10 characters.
`400`	`INVALID_PARAM`	EntityId must be between 1 and 1000 characters.
`400`	`INVALID_PARAM`	Name must consist of 1 to 128 characters.
`403`	`FORBIDDEN`	Requested action cannot be performed as you don't have access over the specified resource.
`500`	`INTERNAL_ERROR`	An internal service error occurred.

HTTP status codes

Status	Description
`200 OK`	Response body contains a list of communication profile IDs.
`400 Bad Request`	Indicates that one or more properties in the request body aren't valid.
`401 Unauthorized`	Request didn't include the authorization token, or the included token expired or isn't valid. Or, you don't have access to the resource.
`403 Forbidden`	Indicates that the authorization token is valid, but the requested operation isn't allowed.
`404 Not Found`	Requested resource not found.
`429 Too Many Requests`	Permitted rate limit, specified as the number of requests per unit of time, exceeded. You can retry the request by using exponential back-off.
`500 Server Error`	Error occurred on the server. You can retry the request by using exponential back-off.
`503 Service Unavailable`	Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request.

Delete communication profile

Delete the specified communication profile. This operation completes the following actions:

Disables the communication capability.
Deletes the profileId assigned to a unit.
Delete any contacts in address books where profileID is the contact.

This operation is available in the following countries.

Healthcare	Hospitality	Senior Living	Core
US	US, UK, FR, CA, IT, DE, ES, JP	US, UK, FR, CA, IT, DE, ES, JP	US

Request

To remove a profile, you make a DELETE request to the /v1/communications/profile resource.

Request path and header example

Copied to clipboard.

DELETE /v1/communications/profile/{profileId} HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {access token}

Request path and header parameters

Parameter	Located in	Description	Type	Required
`profileId`	Path	Identifies the communication profile. Formatted as an Amazon Common Identifier (ACI), `amzn1.alexa.communications.profile.did.{id}`.	String	Yes
`access token`	Header	Access token for the customer. Set to an LWA token.	String	Yes

Request body example

The request has no body.

Request body properties

The request has no body.

Response

A successful response returns HTTP 204 No Content. On error, the response returns the appropriate HTTP status code and includes a response body with a message string that describes the error.

Response body example

The response has no body.

Response body properties

The response has no body.

HTTP status codes

Status	Description
`204 No Content`	Communications profile deleted successfully.
`400 Bad Request`	Indicates that one or more properties in the request body aren't valid. The request wasn't valid for one of the following reasons: The `profileId` is not valid.
`401 Unauthorized`	Request didn't include the authorization token, or the included token expired or isn't valid. Or, you don't have access to the resource.
`403 Forbidden`	Indicates that the authorization token is valid, but the requested operation isn't allowed.
`404 Not Found`	Requested resource not found.
`429 Too Many Requests`	Permitted rate limit, specified as the number of requests per unit of time, exceeded. You can retry the request by using exponential back-off.
`500 Server Error`	Error occurred on the server. You can retry the request by using exponential back-off.
`503 Service Unavailable`	Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request.

Get communication profile

Get the details of the specified communication profile, including the unit ID associated with the profile.

This operation is available in the following countries.

Healthcare	Hospitality	Senior Living	Core
US	US, UK, FR, CA, IT, DE, ES, JP	US, UK, FR, CA, IT, DE, ES, JP	US

Request

To get the profile, you make a GET request to the /v1/communications/profile resource.

Request path and header example

Copied to clipboard.

GET /v1/communications/profile/{profileId} HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {access token}

Request path and header parameters

Parameter	Located in	Description	Type	Required
`profileId`	Path	Identifies the communication profile. Formatted as an Amazon Common Identifier (ACI), `amzn1.alexa.communications.profile.did.{id}`.	String	Yes
`access token`	Header	Access token for the customer. Set to an LWA token.	String	Yes

Request body example

The request has no body.

Request body properties

The request has no body.

Response

A successful response returns HTTP 200 OK, along with the communications profile. On error, the response returns the appropriate HTTP status code and includes a response body with a message string that describes the error.

Response body example

{
    "entity": {
        "type": "UNIT",
        "id": "amzn1.alexa.unit.did.101"
    },
    "name": "Room 101",
    "profileId": {
        "profileId": "amzn1.alexa.communications.profile.did.1234"
    }
}

Response body properties

Property	Description	Type
`entity`	Entity, such as the unit, for which to fetch the communications profile.	Object
`entity.type`	Type of entity. Valid value: `UNIT`.	String
`entity.id`	Identifies the unit. Formatted as an Amazon Common Identifier (ACI), `amzn1.alexa.unit.did.{id}`.	String
`name`	Display name for the communication profile. Valid value: 1–50 Unicode (UTF-8) characters	String
`profileId`	Communications profile for the unit.	Object
`profileId.profileId`	Uniquely identifies the communication profile. Formatted as an Amazon Common Identifier (ACI), `amzn1.alexa.communications.profile.did.{id}`.	String

HTTP status codes

Status	Description
`200 OK`	Response body contains the communications profile.
`400 Bad Request`	Indicates that one or more properties in the request body aren't valid. The request wasn't valid for one of the following reasons: The `profileId` is not valid.
`401 Unauthorized`	Request didn't include the authorization token, or the included token expired or isn't valid. Or, you don't have access to the resource.
`403 Forbidden`	Indicates that the authorization token is valid, but the requested operation isn't allowed.
`404 Not Found`	Requested resource not found.
`429 Too Many Requests`	Permitted rate limit, specified as the number of requests per unit of time, exceeded. You can retry the request by using exponential back-off.
`500 Server Error`	Error occurred on the server. You can retry the request by using exponential back-off.
`503 Service Unavailable`	Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request.

Get communication profile by entity

Get the communication profile associated with the specified entity.

This operation is available in the following countries.

Healthcare	Hospitality	Senior Living	Core
US	US, UK, FR, CA, IT, DE, ES, JP	US, UK, FR, CA, IT, DE, ES, JP	US

Request

To get the profile, you make a GET request to the /v1/communications/profile resource.

Request path and header example

Copied to clipboard.

GET /v1/communications/profile?entity.type={type}&entity.id={id}&maxResults={maxResults}&nextToken={nextToken}  HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {access token}

Request path and header parameters

Parameter	Located in	Description	Type	Required
`type`	Query	Type of entity. Valid value: `UNIT`.	String	Yes
`id`	Query	Unit ID. Filters the results to the profile associated with the specified unit.	String	Yes
`access token`	Header	Access token for the customer. Set to an LWA token.	String	Yes

Request body example

The request has no body.

Request body properties

The request has no body.

Response

A successful response returns HTTP 200 OK, along with the communications profile ID for the specified unit. On error, the response returns the appropriate HTTP status code and includes a response body with a message string that describes the error.

Response body example

{
    "entity": {
        "type": "UNIT",
        "id": "amzn1.alexa.unit.did.101"
    },
    "name": "Room 101",
    "profileId": {
        "profileId": "amzn1.alexa.communications.profile.did.1234"
    }
}

Response body properties

Property	Description	Type
`entity`	Entity, such as the unit, for which to fetch the communications profile.	Object
`entity.type`	Type of entity. Valid value: `UNIT`.	String
`entity.id`	Identifies the unit. Formatted as an Amazon Common Identifier (ACI), `amzn1.alexa.unit.did.{id}`.	String
`name`	Display name for the communication profile. Valid value: 1–50 Unicode (UTF-8) characters	String
`profileId`	Communications profile for the unit.	Object
`profileId.profileId`	Uniquely identifies the communication profile. Formatted as an Amazon Common Identifier (ACI), `amzn1.alexa.communications.profile.did.{id}`.	String

HTTP status codes

Status	Description
`200 OK`	Response body contains the communications profile.
`400 Bad Request`	Indicates that one or more properties in the request body aren't valid. The request wasn't valid for one of the following reasons: The provided entity type isn't supported. `UnitId` is not valid. Please check your Input.
`401 Unauthorized`	Request didn't include the authorization token, or the included token expired or isn't valid. Or, you don't have access to the resource.
`403 Forbidden`	Indicates that the authorization token is valid, but the requested operation isn't allowed.
`404 Not Found`	Requested resource not found.
`429 Too Many Requests`	Permitted rate limit, specified as the number of requests per unit of time, exceeded. You can retry the request by using exponential back-off.
`500 Server Error`	Error occurred on the server. You can retry the request by using exponential back-off.
`503 Service Unavailable`	Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request.

Update communication profile

Update the display name for a communication profile.

Note: After you update the display name, existing reciprocal associations for Alexa Smart Properties in senior living units continue to have the previous display name. New reciprocal associations have the new name.

This operation is available in the following countries.

Healthcare	Hospitality	Senior Living	Core
US	US, UK, FR, CA, IT, DE, ES, JP	US, UK, FR, CA, IT, DE, ES, JP	US

Request

To update a profile, you make a PUT request to the /v1/communications/profile/{profileId} resource.

Request path and header example

Copied to clipboard.

PUT /v1/communications/profile/{profileId} HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {access token}

Request path and header parameters

Parameter	Located in	Description	Type	Required
`profileId`	Path	Identifies the communication profile. Formatted as an Amazon Common Identifier (ACI), `amzn1.alexa.communications.profile.did.{id}`.	String	Yes
`access token`	Header	Access token for the customer. Set to an LWA token.	String	Yes

Request body example

Copied to clipboard.

{
  "name": "Room 14-101"
}

Request body properties

Property Description Type Required

Property	Description	Type	Required
`name`	Display name for the communication profile. Valid value: 1–50 Unicode (UTF-8) characters that meet the following rules: Characters must be numbers, letters (Chinese characters and non-Roman letters allowed), spaces, apostrophes, dashes, or underscores. Other special characters aren't permitted. Names must contain at least one number or letter.	String	Yes

name

Display name for the communication profile.
Valid value: 1–50 Unicode (UTF-8) characters that meet the following rules:

Characters must be numbers, letters (Chinese characters and non-Roman letters allowed), spaces, apostrophes, dashes, or underscores. Other special characters aren't permitted.
Names must contain at least one number or letter.

String

Yes

Response

A successful response returns HTTP 204 No Content. On error, the response returns the appropriate HTTP status code and includes a response body with a message string that describes the error.

Response body example

The response has no body.

Response body properties

The response has no body.

HTTP status codes

Status	Description
`204 No Content`	Profile name updated successfully.
`400 Bad Request`	Indicates that one or more properties in the request body aren't valid. The request wasn't valid for one of the following reasons: The `profileId` is not valid. `Name` is not valid. `Name` is required.
`401 Unauthorized`	Request didn't include the authorization token, or the included token expired or isn't valid. Or, you don't have access to the resource.
`403 Forbidden`	Indicates that the authorization token is valid, but the requested operation isn't allowed.
`404 Not Found`	Requested resource not found.
`429 Too Many Requests`	Permitted rate limit, specified as the number of requests per unit of time, exceeded. You can retry the request by using exponential back-off.
`500 Server Error`	Error occurred on the server. You can retry the request by using exponential back-off.
`503 Service Unavailable`	Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request.

Create reciprocal association

Important: The reciprocal association feature is only available for properties that have an Alexa Smart Properties in senior living subscription.

Create a reciprocal association between the specified unit and an external contact. The association allows the external contact to place an inbound call to an Alexa-enabled device associated with the unit. To create the association, you add the external contact to the address book associated with the property unit, and then create a reciprocal association between the room and the contact.

This operation adds the communication profile of the unit as a contact in the address book of the external user identified by contact ID. And, then sends an Alexa message to the external contact's Alexa app and Amazon Echo devices to inform them about the new reciprocal contact. If an external contact has multiple phone numbers, this operation attempts to create reciprocal association with each valid phone number. If an association with at least one phone number succeeds, the operation succeeds. For phone numbers that already have a reciprocal association, this operation doesn't create a duplicate contact or send a message to the external contact.

After you create the association, the external contact can view the contact to the unit in the contacts list on their Alexa-enabled devices and in the Alexa app and place calls to the unit by using voice or on-screen controls on Alexa-enabled devices with a screen. The external contact can block the unit contact if they wish. Messaging and drop-in calling aren't supported with the inbound calling feature.

Note: Before you use this operation, you must create the external contact and add it to the address book of the unit. For more details, see create contact and create address book association.

Tip: If you associate an address book with a unit, wait at least one to two minutes to create a reciprocal association. After you create the address book association, propagation to the unit happens asynchronously. If you call this operation too soon, you might see a HTTP 400 Bad Request with the reason that an address book isn't associated with the specified unit. Here, retry the reciprocal association.

This operation is available in the following countries.

Healthcare	Hospitality	Senior Living	Core
None	JP	US, UK, FR, CA, IT, DE, ES, JP	None

Request

To create an association, you make a POST request to the /v1/communications/profile/{profileId}/reciprocalAssociations resource.

Request path and header example

Copied to clipboard.

POST /v1/communications/profile/{profileId}/reciprocalAssociations HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {access token}

Request path and header parameters

Parameter	Located in	Description	Type	Required
`profileId`	Path	Identifies the communication profile for the unit. Formatted as an Amazon Common Identifier (ACI), `amzn1.alexa.communications.profile.did.{id}`.	String	Yes
`access token`	Header	Access token for the customer. Set to an LWA token.	String	Yes

Request body example

Copied to clipboard.

{
    "contact": {
        "contactId": "amzn1.alexa.contact.did.1101"
    }
}

Request body properties

Property	Description	Type	Required
`contact`	Identifies the external contact to associate with the unit.	Object	Yes
`contact.contactId`	Identifies the external contact. Make sure that the contact is in the address book associated with the unit specified by the `profileId`. If the contact has multiple phone numbers, this operation allows inbound calling for all numbers. Formatted as an Amazon Common Identifier (ACI), `amzn1.alexa.contact.{id}`.	String	Yes

Response

A successful response returns HTTP 201 Created, along with the association. On error, the response returns the appropriate HTTP status code and includes a response body with a message string that describes the error.

HTTP status codes

Status	Description
`204 No Content`	Reciprocal association created successfully.
`400 Bad Request`	Indicates that one or more properties in the request body aren't valid. The request wasn't valid for one of the following reasons: The `profileId` is not valid. The contact has not enabled Communications in their Alexa app. You can add only the contacts that are enabled with Alexa Communications. The AddressBook, in which contact is created, is not associated with entity for profileId.
`401 Unauthorized`	Request didn't include the authorization token, or the included token expired or isn't valid. Or, you don't have access to the resource.
`403 Forbidden`	Indicates that the authorization token is valid, but the requested operation isn't allowed.
`404 Not Found`	Requested resource not found.
`429 Too Many Requests`	Permitted rate limit, specified as the number of requests per unit of time, exceeded. You can retry the request by using exponential back-off.
`500 Server Error`	Error occurred on the server. You can retry the request by using exponential back-off.
`503 Service Unavailable`	Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request.

Delete a reciprocal association status

Important: The reciprocal association feature is only available for properties that have an Alexa Smart Properties in senior living subscription.

To disable inbound calling from an external contact to the unit, delete the reciprocal association between the unit and the external contact. This operation removes the specified unit from the address book of the specified contact, and sends an Alexa message to the contact's Alexa app and Amazon Echo devices to inform the contact that the association was deleted.

Tip: When you delete a contact or communication profile or disassociate an address book from a unit, all reciprocal associations for the unit are deleted automatically. In each of these cases, no message is sent to external contacts. Amazon recommends that you delete reciprocal associations for a given contact before you delete the contact or communication profile or disassociate an address book from a unit so that the external contact receives a message.

Note: If a contact has multiple phones numbers, this operation deletes the association for all phone numbers listed for the contact. The operation succeeds when all numbers are deleted and fails otherwise.

This operation is available in the following countries.

Healthcare	Hospitality	Senior Living	Core
None	JP	US, UK, FR, CA, IT, DE, ES, JP	None

Request

To remove an association, you make a DELETE request to the /v1/communications/profile/{profileId}/reciprocalAssociations resource.

Request path and header example

Copied to clipboard.

DELETE /v1/communications/profile/{profileId}/reciprocalAssociations?contactId={contactId} HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {access token}

Request path and header parameters

Parameter	Located in	Description	Type	Required
`profileId`	Path	Identifies the communication profile of the unit from which you want to disable inbound calling from the contact. Formatted as an Amazon Common Identifier (ACI), `amzn1.alexa.communications.profile.did.{id}`.	String	Yes
`contactId`	Query	Identifies the external contact. Formatted as an Amazon Common Identifier (ACI), `amzn1.alexa.contact.{id}`.	String	Yes
`access token`	Header	Access token for the customer. Set to an LWA token.	String	Yes

Request body example

The request has no body.

Request body properties

The request has no body.

Response

A successful response returns HTTP 204 No Content. On error, the response returns the appropriate HTTP status code and includes a response body with a message string that describes the error.

Response body example

The response has no body.

Response body properties

The response has no body.

HTTP status codes

Status	Description
`204 No Content`	Reciprocal association for the specified contact deleted successfully.
`400 Bad Request`	Indicates that one or more properties in the request body aren't valid. The request wasn't valid for one of the following reasons: The `profileId` is not valid. The `contactId` is not valid. The AddressBook, in which contact is created, is not associated with entity for `profileId`.
`401 Unauthorized`	Request didn't include the authorization token, or the included token expired or isn't valid. Or, you don't have access to the resource.
`403 Forbidden`	Indicates that the authorization token is valid, but the requested operation isn't allowed.
`404 Not Found`	Requested resource not found.
`429 Too Many Requests`	Permitted rate limit, specified as the number of requests per unit of time, exceeded. You can retry the request by using exponential back-off.
`500 Server Error`	Error occurred on the server. You can retry the request by using exponential back-off.
`503 Service Unavailable`	Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request.

Get reciprocal association

Important: The reciprocal association feature is only available for properties that have an Alexa Smart Properties in senior living subscription.

Get the reciprocal association status between the specified profile and contact.

This operation is available in the following countries.

Healthcare	Hospitality	Senior Living	Core
None	JP	US, UK, FR, CA, IT, DE, ES, JP	None

Request

To get the association, you make a GET request to the /v1/communications/profile/{profileId}/reciprocalAssociations resource.

Request path and header example

Copied to clipboard.

GET /v1/communications/profile/{profileId}/reciprocalAssociations?contactId={contactId} HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {access token}

Request path and header parameters

Parameter	Located in	Description	Type	Required
`profileId`	Path	Identifies the communication profile for the unit. Formatted as an Amazon Common Identifier (ACI), `amzn1.alexa.communications.profile.did.{id}`.	String	Yes
`contactId`	Query	Identifies the external contact associated with the `profileId`. Formatted as an Amazon Common Identifier (ACI), `amzn1.alexa.contact.{id}`.	String	Yes
`access token`	Header	Access token for the customer. Set to an LWA token.	String	Yes

Request body example

The request has no body.

Request body properties

The request has no body.

Response

A successful response returns HTTP 200 OK, along with the association status. On error, the response returns the appropriate HTTP status code and includes a response body with a message string that describes the error.

Response body example

{
    "results": [{
        "contact": {
            "contactId": "amzn1.alexa.contact.1101"
        },
        "status": "ENABLED"
    }],
    "paginationContext": {
        "nextToken": "null"
    }
}

Response body properties

Property	Description	Type
`results`	List of contacts.	Array of objects
`results[].contact`	Defines the contact.	Object
`results[].contact.contactId`	Identifies the external contact associated with the `profileId`. Formatted as an Amazon Common Identifier (ACI), `amzn1.alexa.contact.{id}`.	String
`results[].status`	Indicates whether a reciprocal association exists between the specified contact and profile. If an external contact has multiple phone numbers and any of the phone numbers listed in the contact have a reciprocal contact created for the unit, the status is `ENABLED`. Valid values: `ENABLED`, `DISABLED`.	String
`paginationContext`	Indicates whether there are more results to return.	Object
`paginationContext.nextToken`	Included when the response is truncated. Use this value in a subsequent request with the same filter parameters as this request. If no more results, `nextToken` is null.	String

HTTP status codes

Status	Description
`200 OK`	Response contains the association status.
`400 Bad Request`	Indicates that one or more properties in the request body aren't valid. The request wasn't valid for one of the following reasons: The `profileId` is not valid. The `contactId` is not valid The contact has not enabled Communications in their Alexa app. You can add only the contacts that are enabled with Alexa Communications. The AddressBook, in which contact is created, is not associated with entity for `profileId`.
`401 Unauthorized`	Request didn't include the authorization token, or the included token expired or isn't valid. Or, you don't have access to the resource.
`403 Forbidden`	Indicates that the authorization token is valid, but the requested operation isn't allowed.
`404 Not Found`	Requested resource not found.
`429 Too Many Requests`	Permitted rate limit, specified as the number of requests per unit of time, exceeded. You can retry the request by using exponential back-off.
`500 Server Error`	Error occurred on the server. You can retry the request by using exponential back-off.
`503 Service Unavailable`	Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request.

Create blocking rule

Important: The drop-in feature is only available for properties that have an Alexa Smart Properties in senior living subscription.

Creates a blocking rule to enable or disable calling and messaging between two property units.

This operation is available in the following countries.

Healthcare	Hospitality	Senior Living	Core
US	US	US	US

Request

To create a blocking rule, you make a PUT request to the v1/communications/profile/{profileId}/contacts/settings/Block resource. The rule blocks the target unit from calling the specified unit, identified by profile IDs. However, the specified unit can still call the target unit.

Request header example

Copied to clipboard.

PUT /v1/communications/profile/{profileId}/contacts/settings/Block?alexaCommunicationProfileId={alexaCommunicationProfileId} HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {access token}

Request header and path parameters

Parameter	Located in	Description	Type	Required
`profileId`	Path	Identifies the communication profile for the unit for which to update the drop-in setting. Formatted as an Amazon Common Identifier (ACI), `amzn1.alexa.communications.profile.did.{id}`.	String	Yes
`alexaCommunicationProfileId`	Query	Identifies the communication profile for the target unit for which to enable or disable drop-in on `profileId`. Formatted as an Amazon Common Identifier (ACI), `amzn1.alexa.communications.profile.did.{id}`.	String	Yes
`access token`	Header	Access token for the customer. Set to an LWA token.	String	Yes

Request body example

Copied to clipboard.

{
        "value": "ENABLED"
}

Request body properties

Parameter	Description	Type	Required
`value`	Setting to enable or block communications to the unit. Valid values: `ENABLED`, `DISABLED`.	String	Yes

Response

A successful response returns HTTP 204 No Content. On error, the response returns the appropriate HTTP status code and includes a response body with a message string that describes the error.

Response body example

The response has no body.

Response body parameters

The response has no body.

HTTP status codes

Status	Description
`204 No content`	The request succeeded.
`400 Bad Request`	Indicates that one or more properties in the request body aren't valid. The request wasn't valid for one of the following reasons: • The specified `profileId` isn't valid. • The source and target communication profile IDs can't be the same. That is, `profileId` can't be the same as `alexaCommunicationProfileId`.
`401 Unauthorized`	Request didn't include the authorization token, or the included token expired or isn't valid. Or, you don't have access to the resource.
`403 Forbidden`	Indicates that the authorization token is valid, but the requested operation isn't allowed.
`404 Not Found`	Requested resource not found.
`429 Too Many Requests`	Permitted rate limit, specified as the number of requests per unit of time, exceeded. You can retry the request by using exponential back-off.
`500 Server Error`	Error occurred on the server. You can retry the request by using exponential back-off.
`503 Service Unavailable`	Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request.

Get blocking rule settings

Important: The drop-in feature is only available for properties that have an Alexa Smart Properties in senior living subscription.

Gets a blocking rule that enables or disables inbound calling and messaging between property units.

This operation is available in the following countries.

Healthcare	Hospitality	Senior Living	Core
US	US	US	US

Request

To get a blocking rule, you make a GET request to the /v1/communications/profile/{profileId}/contacts/settings/Block?value={value} resource.

Request header example

Copied to clipboard.

GET /v1/communications/profile/{profileId}/contacts/settings/Block?value={value}&alexaCommunicationProfileId={alexaCommunicationProfileId} HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {access token}

Request header and path parameters

Parameter	Located in	Description	Type	Required
`profileId`	Path	Identifies the communication profile for the unit for which to query the drop-in settings. Formatted as an Amazon Common Identifier (ACI), `amzn1.alexa.communications.profile.did.{id}`.	String	Yes
`alexaCommunicationProfileId`	Query	Identifies the communication profile for the target unit. If not provided, the response includes a list of all the targets to whom calling to the `profileId` is allowed or blocked. Formatted as an Amazon Common Identifier (ACI), `amzn1.alexa.communications.profile.did.{id}`.	String	No
`value`	Query	Filter on the blocking rule setting status. Valid values: `ENABLED`, `DISABLED`.	String	No
`maxResults`	Query	Maximum number of results to return in the response. Valid values: 1–100. Default: 10.	Integer	No
`nextToken`	Query	Token from the previous response. Include if iterating over a paginated response. If this token isn't present, the response contains the first page of results. For details, see Handling Pagination in Query Results.	String	No

Request body example

The request has no body.

Request body properties

The request has no body.

Response

A successful response returns HTTP 200 OK, along with a list of blocking rule settings for each target profile ID. On error, the response returns the appropriate HTTP status code and includes a response body with a message string that describes the error.

Response body example

The following example shows the body of a successful response.

{
    "results": [{
            "setting": "Block",
            "contactId": "amzn1.alexa.contact.did.1101",
            "alexaCommunicationProfileId": "amzn1.alexa.communications.profile.did.2101",
            "value": "DISABLED"
        },
        {
            "setting": "Block",
            "contactId": "amzn1.alexa.contact.did.1102",
            "alexaCommunicationProfileId": "amzn1.alexa.communications.profile.did.2102",
            "value": "ENABLED"
        }
    ],
    "paginationContext": {
        "nextToken": ""
    }
}

Response body properties

Property	Description	Type
`results`	List of contacts and associated block settings.	Array of objects
`results[].setting`	Setting type. Always set to `Block`.	String
`results[].contactId`	Identifies the external contact associated with the target unit identified by the `alexaCommunicationProfileId`. Formatted as an Amazon Common Identifier (ACI), `amzn1.alexa.contact.{id}`.	String
`results[].alexaCommunicationProfileId`	Identifies the communication profile for the target unit. Formatted as an Amazon Common Identifier (ACI), `amzn1.alexa.communications.profile.did.{id}`.	String
`results[].value`	Current status of the block setting. Valid values: `ENABLED`, `DISABLED`.	String
`paginationContext`	Indicates whether there are more results to return.	Object
`paginationContext.nextToken`	Included when the response is truncated. Use this value in a subsequent request with the same filter parameters as this request. If no more results, `nextToken` is null.	String

HTTP status codes

Status	Description
`200 OK`	Response body contains a list of block settings per contact.
`400 Bad Request`	Indicates that one or more properties in the request body aren't valid. The request wasn't valid for one of the following reasons: The `profileId` is not valid. Allowed Values for DropIn settingKey : [ENABLED, DISABLED].
`401 Unauthorized`	Request didn't include the authorization token, or the included token expired or isn't valid. Or, you don't have access to the resource.
`403 Forbidden`	Indicates that the authorization token is valid, but the requested operation isn't allowed.
`404 Not Found`	Requested resource not found.
`429 Too Many Requests`	Permitted rate limit, specified as the number of requests per unit of time, exceeded. You can retry the request by using exponential back-off.
`500 Server Error`	Error occurred on the server. You can retry the request by using exponential back-off.
`503 Service Unavailable`	Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request.

Get drop-in settings

Important: The drop-in feature is only available for properties that have an Alexa Smart Properties in healthcare subscription.

Get the current state of the drop-in setting of the specified profile ID for each target unit.

This operation is available in the following countries.

Healthcare	Hospitality	Senior Living	Core
US	None	None	None

Request

To get the settings, you make a GET request to the /v1/communications/profile/{sourceProfileId}/contacts/settings/DropIn resource.

Request path and header example

Copied to clipboard.

GET /v1/communications/profile/{profileId}/contacts/settings/DropIn?alexaCommunicationProfileId={alexaCommunicationProfileId}  
HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {access token}

Request path and header parameters

Parameter	Located in	Description	Type	Required
`profileId`	Path	Identifies the communication profile for the unit for which to query the drop-in settings. Formatted as an Amazon Common Identifier (ACI), `amzn1.alexa.communications.profile.did.{id}`.	String	Yes
`alexaCommunicationProfileId`	Query	Identifies the communication profile for the target unit. If not provided, the response includes a list of all the targets to whom drop-in permission is allowed or disallowed from the `profileId`. Formatted as an Amazon Common Identifier (ACI), `amzn1.alexa.communications.profile.did.{id}`.	String	No
`value`	Query	Filter on the Drop-in setting status. Valid values: `ENABLED`, `DISABLED`.	String	No
`maxResults`	Query	Maximum number of results to return in the response. Valid values: 1–100. Default: 10.	Integer	No
`nextToken`	Query	Token from the previous response. Include if iterating over a paginated response. If this token isn't present, the response contains the first page of results. For details, see Handling Pagination in Query Results.	String	No

Request body example

The request has no body.

Request body properties

The request has no body.

Response

A successful response returns HTTP 200 OK, along with a list of drop-in settings for each target profile ID. On error, the response returns the appropriate HTTP status code and includes a response body with a message string that describes the error.

Response body example

{
    "results": [{
        "setting": "DropIn",
        "contactId": "amzn1.alexa.contact.did.1101",
        "alexaCommunicationProfileId": "amzn1.alexa.communications.profile.did.2101",
        "value": "DISABLED"
    }],
    "paginationContext": {
        "nextToken": null
    }
}

Response body properties

Property	Description	Type
`results`	List of contacts and associated drop-in settings.	Array of objects
`results[].setting`	Setting type. Always set to `Dropin`.	String
`results[].contactId`	Identifies the external contact associated with the target unit identified by the `alexaCommunicationProfileId`. Formatted as an Amazon Common Identifier (ACI), `amzn1.alexa.contact.{id}`.	String
`results[].alexaCommunicationProfileId`	Identifies the communication profile for the target unit. Formatted as an Amazon Common Identifier (ACI), `amzn1.alexa.communications.profile.did.{id}`.	String
`results[].value`	Current status of the drop-in setting. Valid values: `ENABLED`, `DISABLED`.	String
`paginationContext`	Indicates whether there are more results to return.	Object
`paginationContext.nextToken`	Included when the response is truncated. Use this value in a subsequent request with the same filter parameters as this request. If no more results, `nextToken` is null.	String

HTTP status codes

Status	Description
`200 OK`	Response body contains a list of drop-in settings per contact.
`400 Bad Request`	Indicates that one or more properties in the request body aren't valid. The request wasn't valid for one of the following reasons: The `profileId` is not valid. Allowed Values for DropIn settingKey : [ENABLED, DISABLED].
`401 Unauthorized`	Request didn't include the authorization token, or the included token expired or isn't valid. Or, you don't have access to the resource.
`403 Forbidden`	Indicates that the authorization token is valid, but the requested operation isn't allowed.
`404 Not Found`	Requested resource not found.
`429 Too Many Requests`	Permitted rate limit, specified as the number of requests per unit of time, exceeded. You can retry the request by using exponential back-off.
`500 Server Error`	Error occurred on the server. You can retry the request by using exponential back-off.
`503 Service Unavailable`	Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request.

Set drop-in preference

Important: The drop-in feature is only available for properties that have an Alexa Smart Properties in healthcare subscription.

Enable or disable the drop-in preference between the specified healthcare units. An enabled drop-in setting allows a target unit, linked with alexaCommunicationProfileId, to drop in on a unit, linked with a profileId. Similar to an intercom, drop-in lets you connect directly with a contact. To set up drop-in, both the source unit, such as a patient room, and the target unit, such as a nurses station, must have the other unit as a contact in their associated address book. Drop-in is one way, from the target unit to the source unit.

Note: This configuration allows the target to drop in on the patient. However, the target unit is in the patients contact list. To minimize the chance of a patient calling a target that might not be available, define the target contact name as something the user is unlikely to use.

This operation is available in the following countries.

Healthcare	Hospitality	Senior Living	Core
US	None	None	None

Request

To update the drop-in setting, you make a PUT request to the /v1/communications/profile/{profileId}/contacts/settings resource.

Request path and header example

Copied to clipboard.

PUT /v1/communications/profile/{profileId}/contacts/settings/DropIn?alexaCommunicationProfileId={alexaCommunicationProfileId} HTTP/1.1
Host: api.amazonalexa.com
Accept: application/json
Authorization: Bearer {access token}

Request path and header parameters

Parameter	Located in	Description	Type	Required
`profileId`	Path	Identifies the communication profile for the source unit for which to update the drop-in setting. Formatted as an Amazon Common Identifier (ACI), `amzn1.alexa.communications.profile.did.{id}`.	String	Yes
`alexaCommunicationProfileId`	Query	Identifies the communication profile for the target unit for which to enable or disable drop-in on `profileId`. Formatted as an Amazon Common Identifier (ACI), `amzn1.alexa.communications.profile.did.{id}`.	String	Yes
`access token`	Header	Access token for the customer. Set to an LWA token.	String	Yes

Request body example

Copied to clipboard.

{
        "value": "ENABLED"
}

Request body properties

Property	Description	Type	Required
`value`	Drop-in setting. Valid values: `ENABLED`, `DISABLED`.	String	Yes

Response

A successful response returns HTTP 204 No Content. On error, the response returns the appropriate HTTP status code and includes a response body with a message string that describes the error.

Response body example

The response has no body.

Response body properties

The response has no body.

HTTP status codes

Status	Description
`204 No Content`	Drop-in setting updated successfully.
`400 Bad Request`	Indicates that one or more properties in the request body aren't valid. The request wasn't valid for one of the following reasons: The `profileId` is not valid. Allowed Values for DropIn settingKey : [ENABLED, DISABLED].
`401 Unauthorized`	Request didn't include the authorization token, or the included token expired or isn't valid. Or, you don't have access to the resource.
`403 Forbidden`	Indicates that the authorization token is valid, but the requested operation isn't allowed.
`404 Not Found`	Requested resource not found.
`429 Too Many Requests`	Permitted rate limit, specified as the number of requests per unit of time, exceeded. You can retry the request by using exponential back-off.
`500 Server Error`	Error occurred on the server. You can retry the request by using exponential back-off.
`503 Service Unavailable`	Server is down for maintenance, overloaded, or otherwise unavailable to handle the incoming request.

Was this page helpful?

Provide feedback

Last updated: Dec 04, 2024