Mis consolas Alexa
Identificarse
Identificarse
Gracias por tu visita. Esta página solo está disponible en inglés.

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 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"
            }
          }
        }
      }]
    }
  }
}