Message Import

One core part of the API is the import of messages into hotelkit. Imported messages are called handover in this documentation.
There are two endpoints for this matter: On the one hand an endpoint for creating a message within hotelkit. Those endpoints can be found at /requests?type=[type]. On the other hand, there is an endpoint for creating and editing message templates/request types.

What are Request Types

A request type is a message template that defines which attributes are needed for a single message to be successfully imported to hotelkit.

A customer is able to define settings for each request type seperately.
Recipients of the requests (given recipients are not sent via the API), how long is the information valid, how sensible is the information sent etc.

In order to add the biggest value and enhance efficiency it is important that there are multiple request types in case there are different imports for different groups of people.

For example: a partner wants to import different types of reports: A daily report, a more condensed monthly report and an annual report with just the key performances of the business. The partner would create 3 separate request types as the customer could want to forward these kinds of reports to different recipients.

After setting the request type, it has to be enabled for the customer and requests can be created. For this documentation purpose a request type complete_type was created with every option activated. It is convenient for documentation but should be not a realistic approach as every request_type should only consist of its necessary parts.

Process

Typically, the following steps have to be taken in order to make an import possible to hotelkit:

1. Define use case (requestType)
   At first the use case of the import needs to be defined. In hotelkit a template will be created for each use case where the property can configure further details in hotelkit. Definition of the use case must be done via PUT /setup/requests.

2. Enable use cases in property
   To be able to use individual configurations for the properties, use cases are not enabled for all properties but must be activated on a property level. There are two ways to achieve that:

   1. Via PUT /setup/customer If the use cases are on a property-based level and can vary between those properties it is the best practice that the partner is in control of active use case management. The details on how to manage the use cases should be discussed in the development meetings prior to an implementation.

   2. Customer Success team of hotelkit activates use cases on initial set up of integration.
      If the requestType is configured as enabledByDefault the requestTypes will be accessible for a newly activated integration by our CSM team. It still can be configured by the partner.

3. Import cases to property
   To import actual content into the properties the endpoint POST /requests must be used.

“ActionButtons”

Requests can be imported with ActionButtons. ActionButtons are a simple way to implement a task-like workflow. This can be a suitable solution for importing tasks as a handover.
The following sequence explains the process of importing with action buttons.

1. POST /request with RequestAction

2. optional ActionSendBack

3. optional followUpctions

ActionButtons require a referenceID in order to trigger an ActionSendBack.

The use of ActionButtons can therefore be highly personalised. In order to trigger FollowUpActions, it is necessary to first send the ActionSendBack.
The followUpActions are described in the same scheme as the RequestActions.

Updating Handovers

It is possible to update already created handovers with the endpoint PUT /requests/{referenceID}. All values must be resent, especially in the body. This means that values that are not resent are removed when the handover is updated. This also applies to attachments. Required values that are not submitted will be empty after the update.
In hotelkit, there is a new notification for all recipients after the handover update.

It is not possible to make changes to the referenceID or creator.

Use cases:

1. Modification of the initial import: for example, the room service or the comment from the guest changes

2. A guest cancels his/her request: in this case, you can close the status (remove actionButtons) of the request and change the title so that it is clear that the request has been cancelled.

Deleting Handovers

An imported handover can be removed in hotelkit by using DELETE /requests/{referenceID}.

This action can be used to clear your test environment. Usually in production this endpoint is not needed.

Setting “final”: true removes the entry completely and it can not be restored. Using false archieves the handover. The entry can be restored manually by hotelkit upon request.

We suggest using “final”:false.

Content Formatting

The transmitted information in the “content” of the request can be formatted using HTML.

HTML-Header and the <DOCTYPE html> are not supported. Instead use the variety of the html-Body with this allowed classes:

Furter information can be found on HTML Purifier.

To send a youtube video in the content please use this structure.

<img src="http://img.youtube.com/vi/dQw4w9WgXcQ/0.jpg" />
Instead of the BOLD code insert the ID of the video as it is found in the youtube-url.

Additionally you can add attributes for width and heights.

Updating Request Types

The created request types (templates) can be changed via PUT /setup/requests.

The changes are not applied automatically. The client can make individual adjustments to e.g. the title, that we don’t want to override unintentionally.

Made changes are global and will be applied on new integration setups or when PUT /setup/customer is called while sending the enabledRequests for existing integrations.

Endpoint Documentation

Information about the usage of headers and the signature is found in Getting Started and Security.