Alexa.Business.Reservation.Room Interface
You can use the Alexa for Business Room Booking API to build a skill to manage meeting room reservations. The Alexa.Business.Reservation.Room
interface describes messages that you can use to create, update, or search for meeting room reservations.
For more information about meetings skills, see Understand Meetings Skills.
For information on setting up Alexa for Business in your organization, see Understand Alexa for Business.
For the list of locales that are supported for the Room
interface, see List of Capability Interfaces and Supported Locales.
- API endpoint and authentication
- The reservation object
- Directives
- Search object properties
- Search Examples
API endpoint and authentication
The API endpoint is https://api.amazonalexa.com.
Before you can use the Alexa.Business.Reservation.Room
interface, you must set up account linking for your skill. Each API request must contain the access token from the room-booking application that is linked to your skill. For more information, see Configure account linking.
The reservation object
The Alexa.Business.Reservation.Room
interface uses the reservation
object as the primary data object. The reservation
object contains a meeting
object.
Reservation example
"reservation": {
"id": "<reservation id>",
"roomId": "<room id>",
"interval": {
"start": "2018-05-30T09:00:00Z",
"end": "2018-05-30T09:30:00Z"
},
"meeting": {
"organizer": "Jane Doe",
"title": "Status Meeting"
}
}
Reservation details
Field | Description | Type | Required |
---|---|---|---|
id |
The identifier for the reservation. | String. The maximum length is 255 characters. | Not included in the create directive. Included in the update directive. Required in responses. |
roomId |
The identifier for the room to reserve. | String. The maximum length is 100 characters. | No |
interval |
The time interval during which to reserve the room. | An interval object. | Yes |
meeting |
The details of the meeting to create. | A meeting object as described following. | No |
Meeting details
Field | Description | Type | Required |
---|---|---|---|
organizer |
The name of the organizer of the meeting. | String | No |
title |
The title of the meeting. | String | No |
Directives
Create directive
Support the Create
directive so that customers can reserve a meeting room. The customer requests a room for a specific date and time.
The following example shows a customer utterance:
Alexa, book this meeting room for thirty minutes.
Create directive payload details
Field | Description | Type | Required |
---|---|---|---|
context |
Information about the location from which the customer is making the request. This is the room that contains the Alexa device that the customer is talking to. | Object | Yes |
idempotencyToken |
An identifier to help you manage idempotency across message requests. | String | Yes |
reservation |
The reservation to create. | A reservation object. | Yes |
Create directive example
{
"directive": {
"header": {
"namespace": "Alexa.Business.Reservation.Room",
"name": "Create",
"interfaceVersion": "1.0",
"messageId": "<message id>"
},
"authorization": {
"type": "BearerToken",
"token": "<a bearer token>"
},
"payload": {
"context": {
"sourceLocation": {
"room": {
"id": "<the room from which the request is made>"
}
}
},
"idempotencyToken": "<token>",
"reservation": {
"roomId": "<room id>",
"interval": {
"start": "2018-05-30T09:00:00Z",
"end": "2018-05-30T09:30:00Z"
},
"meeting": {
"organizer": "Jane Doe",
"title": "Status Meeting"
}
}
}
}
}
Create response event
If you handle a Create
directive successfully, respond with a CreateResponse
event.
CreateResponse event payload details
Field | Description | Type | Required |
---|---|---|---|
reservation |
The reservation that you created. The id field contains your identifier for the reservation. | A reservation object. | Yes |
CreateResponse event example
{
"event": {
"header": {
"namespace": "Alexa.Business.Reservation.Room",
"name": "CreateResponse",
"interfaceVersion": "1.0",
"messageId": "<message id>"
},
"payload": {
"reservation": {
"id": "<reservation id>",
"interval": {
"start": "2018-05-30T09:00:00Z",
"end": "2018-05-30T09:30:00Z"
}
}
}
}
}
Create directive error handling
If you can't handle a Create
directive successfully, respond with an Alexa.Business.ErrorResponse event.
Update directive
Support the Update
directive so that customers can update their existing meeting room reservations. The update directive contains the original reservation id, and the new room, date, or time that the customer wants. If the update request is not successful, the original reservation is retained and remains unchanged.
Update directive payload details
Field | Description | Type | Required |
---|---|---|---|
context |
Information about the location from which the customer is making the request. This is the room that contains the Alexa device that the customer is talking to. | Object | Yes |
reservation |
The reservation to update and then new details. The original reservation id, and then new room, date, or time that the customer wants. | A reservation object. | Yes |
Update directive example
{
"directive": {
"header": {
"namespace": "Alexa.Business.Reservation.Room",
"name": "Update",
"interfaceVersion": "1.0",
"messageId": "<message id>"
},
"authorization": {
"type": "BearerToken",
"token": "<a bearer token>"
},
"payload": {
"context": {
"sourceLocation": {
"room": {
"id": "<the room from which the request is made>"
}
}
},
"reservation": {
"id": "<existing reservation id>",
"roomId": "<room id>",
"interval": {
"start": "2018-05-30T09:00:00Z",
"end": "2018-05-30T10:00:00Z"
},
"meeting": {
"organizer": "Jane Doe",
"title": "Status Meeting"
}
}
}
}
}
Update response event
If you handle an Update
directive successfully, respond with an UpdateResponse
event.
UpdateResponse event payload details
Field | Description | Type | Required |
---|---|---|---|
reservation |
The reservation that you updated, with the new details. | A reservation object. | Yes |
UpdateResponse event example
{
"event": {
"header": {
"namespace": "Alexa.Business.Reservation.Room",
"name": "UpdateResponse",
"interfaceVersion": "1.0",
"messageId": "<message id>"
},
"payload": {
"reservation": {
"id": "<reservation id>",
"interval": {
"start": "2018-05-30T09:00:00Z",
"end": "2018-05-30T10:00:00Z"
},
"meeting": {
"organizer": "Jane Doe",
"title": "Status Meeting"
}
}
}
}
}
Update directive error handling
If you can't handle an Update
directive successfully, respond with an Alexa.Business.ErrorResponse event. The original reservation must be retained and remain unchanged.
Search directive
Support the Search
directive so that customers can search for available meeting rooms, days, and times. You respond to a search request with an array of results. Customers can search by available status, minimum duration, specific start and end times, and location.
The following example shows a customer utterance:
Alexa, find a room for half an hour.
Search directive payload details
Field | Description | Type | Required |
---|---|---|---|
nextToken |
A token to retrieve additional results if the results are paginated and there are more results. | String | No |
maxResults |
The maximum number of results to return in the current page of results. Results beyond this number are paginated. Specify a number greater than zero. | Integer | Yes |
context |
Information about the location from which the customer is making the request. This is the room that contains the Alexa device that the customer is talking to. | Object | Yes |
query |
The fields to search on. | Object | Yes |
query.availabilities |
The availabilities to include in the search; FREE, TENTATIVE, BUSY. | Array | Yes |
query.minimumDuration |
The minimum duration for the meeting. | A duration object. | No |
query.interval |
The interval over which to search for the meeting. | An interval object. | Yes |
query.minimumCapacity |
The minimum capacity for the meeting room. | Integer | No |
query.location |
A specific location, such as a specific floor, to search for a meeting room. | A location object. | No |
Search directive example
{
"directive": {
"header": {
"namespace": "Alexa.Business.Reservation.Room",
"name": "Search",
"interfaceVersion": "1.0",
"messageId": "<message id>"
},
"authorization": {
"type": "BearerToken",
"token": "<a bearer token>"
},
"payload": {
"nextToken": "<token>",
"maxResults": 5,
"context": {
"sourceLocation": {
"room": {
"id": "<the room from which the request is made>"
}
}
},
"query": {
"availabilities": ["FREE", "TENTATIVE"],
"minimumDuration": "PT1H30M",
"interval": {
"start": "2018-05-30T09:00:00Z",
"end": "2018-05-31T09:00:00Z"
},
"minimumCapacity": 4,
"location": {
"room": {
"id": "1234"
}
}
}
}
}
}
Search response event
If you handle a Search
directive successfully, respond with a SearchResponse
event.
SearchResponse event payload details
Field | Description | Type | Required |
---|---|---|---|
nextToken |
A token to retrieve additional results if the results are paginated and there are more results. | String | No |
availabilities |
The results of the query. | An array of availability objects. | Yes |
SearchResponse event example
{
"event": {
"header": {
"namespace": "Alexa.Business.Reservation.Room",
"name": "SearchResponse",
"interfaceVersion": "1.0",
"messageId": "<message id>"
},
"payload": {
"nextToken": "<token>",
"availabilities": [{
"status": "FREE",
"interval": {
"start": "2018-05-30T09:00:00Z",
"end": "2018-05-30T11:00:00Z"
},
"room": {
"id": "1234",
"name": "Conference Room 1",
"capacity": 8
}
},
{
"status": "TENTATIVE",
"interval": {
"start": "2018-05-30T09:00:00Z",
"end": "2018-05-30T11:00:00Z"
},
"room": {
"id": "5678",
"name": "Conference Room 2",
"capacity": 16
},
"reservation": {
"id": "<reservation id>",
"meeting": {
"organizer": "Jane Doe",
"title": "Status Meeting"
}
}
}]
}
}
}
Search directive error handling
If you can't handle a Search
directive successfully, respond with an Alexa.Business.ErrorResponse event.
Search object properties
The Search
directive uses the following objects.
Interval
The interval object contains information about the start and end time of a meeting, or a range to search for an availability for a meeting.
Interval details
Field | Description | Type | Required |
---|---|---|---|
start |
The start time of the meeting. The start value is inclusive. | A string that uses the RFC 3339 profile of the ISO 8601 format, YYYY-MM-DDThh:mm:ssZ. | Yes |
end |
The end time of the meeting. The end value must be greater than the start value. The end value is exclusive. | A string that uses the RFC 3339 profile of the ISO 8601 format, YYYY-MM-DDThh:mm:ssZ. | Yes |
Interval example
"interval":
{
"start": "2018-05-30T09:00:00Z",
"end": "2018-05-30T09:30:00Z"
}
Location
The location object contains information about the physical location of a room.
Location details
Field | Description | Type | Required |
---|---|---|---|
floor |
The floor that contains the room. | A floor object as described following. | No |
room |
Details about the room. | A room object as described following. | No |
Location example
"location":
{
"floor": {},
"room": {}
}
Floor
The floor object contains information about a floor of a building.
Floor details
Field | Description | Type | Required |
---|---|---|---|
id |
The id of the floor. | String | No |
name |
The friendly name of the floor. | String | No |
Floor example
"floor":
{
"id": "1111",
"name": "Floor 1"
}
Room
Room details
Field | Description | Type | Required |
---|---|---|---|
id |
The unique identifier of the room. | String | Yes |
name |
The friendly name of the room. | String | Yes |
capacity |
The capacity of the room. If you don't have room capacity information, you don't have to provide it. | Integer | No. |
location |
The location of the room. | A location object. | No |
Room example
"room":
{
"id": "1234",
"name": "Conference Room 1",
"capacity": 8,
"location": {}
}
Availability
Availability details
Field | Description | Type | Required |
---|---|---|---|
status |
One of FREE, BUSY, or TENTATIVE. | String | Yes |
interval |
The start and end time for the availability. | An interval object. | Yes |
reservation |
The reservation if it exists. | A reservation object. | Required if status is BUSY. |
room |
The room for the availability. | A room object. | Yes |
Availability example
"availability":
{
"status": "TENTATIVE",
"interval": {
"start": "2018-05-30T09:00:00Z",
"end": "2018-05-30T09:30:00Z"
},
"room": {
"id": "5678",
"name": "Conference Room 2",
"capacity": 16,
"location": {}
},
"reservation": {
"id": "<reservation id>",
"meeting": {
"organizer": "Jane Doe",
"title": "Status Meeting"
}
}
}
Search Examples
Who booked this room? / Is this room free?
This example searches for information about the current room. The following shows the customer utterance:
Alexa, who booked this room?
The following code shows the corresponding search directive request:
{
"directive": {
"header": {
"namespace": "Alexa.Business.Reservation.Room",
"name": "Search",
"interfaceVersion": "1.0",
"messageId": "<message id>"
},
"authorization": {
"type": "BearerToken",
"token": "<a bearer token>"
},
"payload": {
"nextToken": "<token>",
"maxResults": "3",
"context": {
"sourceLocation": {
"room": {
"id": "<the room from which the request is made>"
}
}
},
"query": {
"availabilities": ["BUSY"],
"interval": {
"start": "2018-05-30T09:00:00Z",
"end": "2018-05-31T09:00:00Z"
},
"location": {
"room": {
"id": "1234"
}
}
}
}
}
}
The following code shows the corresponding search response event:
{
"event": {
"header": {
"namespace": "Alexa.Business.Reservation.Room",
"name": "SearchResponse",
"interfaceVersion": "1.0",
"messageId": "<message id>"
},
"payload": {
"nextToken": "<token>",
"availabilities": [{
"status": "BUSY",
"interval": {
"start": "2018-05-30T09:00:00Z",
"end": "2018-05-30T09:30:00Z"
},
"room": {
"id": "1234",
"name": "Conference Room 1"
},
"reservation": {
"id": "<reservation id>",
"meeting": {
"organizer": "Jane Doe",
"title": "Status Meeting"
}
}
}]
}
}
}
Find a room on the third floor
This example searches for a room on the third floor. The following shows the customer utterance:
Alexa, find a room on the third floor.
The following code shows the corresponding search directive request:
{
"directive": {
"header": {
"namespace": "Alexa.Business.Reservation.Room",
"name": "Search",
"interfaceVersion": "1.0",
"messageId": "<message id>"
},
"authorization": {
"type": "BearerToken",
"token": "<a bearer token>"
},
"payload": {
"nextToken": "<token>",
"maxResults": "3",
"context": {
"sourceLocation": {
"room": {
"id": "<the room from which the request is made>"
}
}
},
"query": {
"availabilities": ["FREE"],
"interval": {
"start": "2018-05-30T09:00:00Z",
"end": "2018-05-31T09:00:00Z"
},
"location": {
"floor": {
"name": "3"
}
}
}
}
}
}
The following code shows the corresponding search response event:
{
"event": {
"header": {
"namespace": "Alexa.Business.Reservation.Room",
"name": "SearchResponse",
"interfaceVersion": "1.0",
"messageId": "<message id>"
},
"payload": {
"nextToken": "<token>",
"availabilities": [{
"status": "FREE",
"interval": {
"start": "2018-05-30T09:00:00Z",
"end": "2018-05-30T09:30:00Z"
},
"room": {
"id": "1234",
"name": "Conference Room 1",
"capacity": 8,
"location": {
"floor": {
"name": "3"
}
}
}
}]
}
}
}
Find a room on the third floor for eight people
This example searches for a room on the third floor, for at least eight people. The following shows the customer utterance:
Alexa, find a room on the third floor for eight people.
The following code shows the corresponding search directive request:
{
"directive": {
"header": {
"namespace": "Alexa.Business.Reservation.Room",
"name": "Search",
"interfaceVersion": "1.0",
"messageId": "<message id>"
},
"authorization": {
"type": "BearerToken",
"token": "<a bearer token>"
},
"payload": {
"nextToken": "<token>",
"maxResults": "3",
"context": {
"sourceLocation": {
"room": {
"id": "<the room from which the request is made>"
}
}
},
"query": {
"availabilities": ["FREE"],
"minimumCapacity": 8,
"location": {
"floor": {
"name": "3"
}
},
"interval": {
"start": "2018-05-30T09:00:00Z",
"end": "2018-05-31T09:00:00Z"
}
}
}
}
}
The following code shows the corresponding search response event:
{
"event": {
"header": {
"namespace": "Alexa.Business.Reservation.Room",
"name": "SearchResponse",
"interfaceVersion": "1.0",
"messageId": "<message id>"
},
"payload": {
"nextToken": "<token>",
"availabilities": [{
"status": "FREE",
"interval": {
"start": "2018-05-30T09:00:00Z",
"end": "2018-05-30T09:30:00Z"
},
"room": {
"id": "5678",
"name": "Conference Room 2",
"capacity": 16,
"location": {
"floor": {
"name": "3"
}
}
}
}]
}
}
}