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

Alexa Skills Kit

Other Resources

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

Important: Because a room can contain a location and a location can contain a room, you must avoid creating a circular reference.

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

Important: Because a room can contain a location and a location can contain a room, you must avoid creating a circular reference.

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