In order to communicate with devices on the local hotel network, such as printers, lock systems, PBX, TVs, key cutters or fiscal machines, Mews has introduced the concept of devices and device commands. When a relevant action happens in Mews, a device command is generated and put into the device command queue. Using the API, you can pull the commands from the queue, process them as you find necessary and later mark them as processed. Of course, as many of the actions with devices happen in real time, you should in many cases use this in combination with WebSockets to avoid polling for new commands. Whenever a relevant command is created, you will receive a notification about such an event via the configured WebSocket. For more information on choosing the right option, see Ways to communicate.
Device integrations will require two integrations to be added to a property's Marketplace subscriptions. One is the generic device integration - used for creating the device in Mews. The other is your integration, where the created device must be added under the Connected devices section in the integration settings, so that your system can begin receiving WebSocket notifications of newly created device commands for the selected devices. See Testing your integration below for how to create the devices and link them to your integration.
Note: If using WebSockets, when a new device has been created in Mews and linked to your integration, or removed from your integration, you should disconnect and reconnect to the WebSocket in order to receive WebSocket events for the newly added devices. Currently there is no automatic notification of this, so the property must inform you of any changes to their device set-up.
Using WebSockets, first subscribe your application to receive DeviceCommand events and connect to the WebSockets endpoint.
Once the connection has been established, you will receive notification of all DeviceCommand events in real time.
When you get the Device Command event notification, you can fetch details of the command using Get all commands by ids.
If your application re-connects using WebSockets, or was offline for any reason and for any length of time, you should use the Get all commands operation to retrieve all pending commands that were in the queue while your application was offline. This is to ensure that no commands in the queue remain unprocessed.
Once your application has successfully processed the device command, you should update the status of the command to “Processed” (or other state, if the command was not successfully processed) using the Update command operation.
Mews currently provides several types of Command data, including printer, payment terminal, passport scanner, fiscal machine, and key cutter command data.
For Fiscal Machines (whether a virtual or a physical one), you will receive a command containing Fiscal machine command data. This includes all data of the related Bill, including all the payments and revenue items in the form of an Accounting item.
Note: Currently, there is no way to send fiscal codes generated by the fiscal machine back to Mews.
In case your device is a Key Cutter, you will get a command containing Key cutter command data. You can then use this set of information to encode a physical key card. If your solution includes both physical keys and mobile or other forms of keys, you can also use the same set of information to send the key or door code to the guest.
Ensure you follow our general Guidelines for testing integrations. In addition to this, the following is specific to device integrations:
To be able to use your integration, an additional step of configuring the device and connecting it to the relevant integration (and therefore the API Access Token) is required. This is done through the following steps:
- In Mews Operations, open the main menu in the top left corner, scroll down and click on Marketplace.
- Depending on the type of device you are connecting, click on either the Facility management category (Key cutter integration, Passport scanner integration, Printer integration) or Legal environment (Fiscal machine integration) category.
- Once you have found the correct device integration, click See more followed by Connect to add this device integration to your Marketplace subscription.
- Go into the integrations settings page and complete the required fields (if any), then click on the device type on the left side of the screen (e.g. Key cutters) and then the "+" button to add and configure any required fields of the device (e.g. Identifier). Be sure to save all changes.
- Go back to your integration found in the My subscriptions section of the Marketplace and click on the Settings found on the right side of the integration listing.
- Once inside the integration settings page, you will see a drop down menu titled Connected devices. Select your newly created device from that list and click Save, then restart your WebSocket connection.
This is the same process that will be required when you assist any mutual customer with onboarding and configuration of your solution.
For a full overview of device commands and their states, you can check the device commands queue in Mews. If you are returning an unexpected error indicating there is an issue with the Data JSON, please read this article to understand what this indicates, based on the type of integration you are referring to.