# Access Key Display Help ## Overview The access key modal shows whichever of the three key types are enabled for your facility: **QR Code**, **PIN Code**, and/or **Remote Unlock Button**. Which types appear depends on settings configured by the facility owner: - **Walk-in (same-day check-in)**: controlled by `enabled_key_types` in the Check-in Configuration (`checkin_configurations`) - **Advance booking check-in**: controlled by `enabled_key_types` in the Room Plan Mapping (`room_plan_mappings`) for each plan The Remote Unlock button appears in all three key modals: check-in complete, key info, and checkout complete. --- ## Features ## Feature 1: QR Code Display If QR code is enabled (`enabled_key_types` includes `"qr"`), a QR code is shown at the top of the modal. - Hold the QR code up to the facility's reader to enter - The QR code grays out when it expires - For time-based plans, you can refresh an expired QR automatically or manually See [About QR Code Expiration](key-expiration.md) for details on when keys expire. ## Feature 2: PIN Code Display If PIN code is enabled (`enabled_key_types` includes `"pin"`), a 4–10 digit numeric code is displayed in large block format. | Digit Count | Display Format | |-------------|---------------| | 4 digits | 2 + 2 (with gap) | | 6 digits | 3 + 3 | | 8 digits | 4 + 4 | | 10 digits | 5 + 5 | ### Copying the PIN Code Tap the "Copy" button to copy the PIN to your clipboard. The button turns green with a checkmark to confirm the copy was successful. Copying is disabled when the key has expired. ### How to Use the PIN Code 1. Note the PIN code displayed in the modal 2. Enter the digits on the door keypad 3. The door unlocks ### Why the PIN Code Might Not Appear The PIN code may not appear for the following reasons. - **PIN not enabled in facility settings**: The facility owner has not included `"pin"` in `enabled_key_types` - **Walk-in hourly check-in (keyType=1)**: For walk-in check-ins on time-based (hourly) plans, KEYVOX issues an offline QR code (keyType=1), which does not include a PIN. If you need PIN access, ask the facility owner to review their configuration ## Feature 3: Remote Unlock Button If remote unlock is enabled (`enabled_key_types` includes `"remote_unlock"`), a Remote Unlock button appears at the bottom of the modal. This lets you unlock the door directly from the app without holding your phone up to a reader — just tap the button. The button appears in all three of the following modals: - Check-in complete modal - Key info modal (the screen shown when you tap "View Key" during a stay) - Checkout complete modal ### Button States | State | Label | Icon | |-------|-------|------| | Idle | "Unlock" | Lock icon (blue) | | In progress | "Unlocking..." | Spinning indicator | | Success | "Unlock request sent" | Green checkmark | | Error | "Unlock failed" | Lock icon (red) | | Cooldown | "Unlock (Xs)" | Lock icon (faded) | The "Unlock request sent" success message means the request has reached the KEYVOX cloud. The door's physical unlocking is processed by KEYVOX. ### How to Use Remote Unlock 1. Tap the "Unlock" button 2. Wait for "Unlocking..." with the spinner (typically 1–3 seconds) 3. When "Unlock request sent" appears with a green checkmark, the door is open 4. After 3 seconds, the button enters a 10-second cooldown automatically 5. Once the countdown ends, the button becomes active again ### About the Cooldown Period After a successful unlock or an error, a 10-second cooldown prevents accidental or repeated activations. During cooldown, the remaining seconds are shown, for example: "Unlock (9s)". --- ## Facility Owner Configuration ### Walk-in key type settings (checkin_configurations) The key types displayed for walk-in check-ins are controlled by `enabled_key_types` in the Check-in Configuration screen. | Value | Effect | |-------|--------| | `"qr"` | Show QR code | | `"pin"` | Show PIN code | | `"remote_unlock"` | Show remote unlock button | #### Configuration Examples ```json ["qr"] ``` Default setting (QR code only). Maintains backward compatibility with existing configurations. ```json ["qr", "pin"] ``` Show both QR code and PIN code. ```json ["qr", "remote_unlock"] ``` Show QR code and remote unlock button. ```json ["qr", "pin", "remote_unlock"] ``` Show all three key types. ### Advance booking key type settings (room_plan_mappings) The key types displayed for advance bookings are configured per plan in the Room Plan Mapping. The same `enabled_key_types` values apply. Location: Room Management > target room > "Plan Mappings" section > `enabled_key_types` per plan ### Setting up the lock ID for remote unlock Remote unlock requires both of the following: 1. **KEYVOX account connected**: Complete the KEYVOX integration on the Lock Connection page 2. **Unlock lock ID configured**: On the Lock Connection page, select which lock to unlock for each KEYVOX unit The admin selects the target lock ID directly in the Lock Connection page — guests do not need to choose. For setup instructions see [Lock Connection](lock-connection.md). If no lock ID is configured for a unit, remote unlock returns a "Lock ID not found" error. --- ## Troubleshooting ### Q: The PIN code is not showing Check the following. 1. **Verify facility settings**: Ask the facility owner whether `"pin"` is included in `enabled_key_types` (check-in config for walk-ins, room plan mapping for bookings) 2. **Check the check-in type**: Walk-in check-ins on hourly (time-based) plans use keyType=1 (offline QR), which does not issue a PIN. Accommodation and daily flat plans use keyType=0 and do issue a PIN 3. **Use the QR code instead**: Try entering with the QR code if it is displayed ### Q: The Remote Unlock button is not showing The facility owner needs to add `"remote_unlock"` to `enabled_key_types`. For walk-ins, this is in the check-in configuration; for bookings, it is in the room plan mapping. ### Q: I tapped Remote Unlock but the door did not open Check the following. - Confirm you have a stable internet connection - Ask the facility whether the KEYVOX lock hardware is working normally - Confirm the unlock lock ID is correctly configured for the unit on the Lock Connection page (facility owner action) - Confirm the KEYVOX account integration is active (facility owner action) ### Q: "No keys available" is shown This appears when the connector cannot provide the key types specified in `enabled_key_types`. Contact the facility owner and ask them to verify that the `enabled_key_types` setting in the check-in configuration or room plan mapping matches the KEYVOX configuration. ### Q: Remote unlock showed an error Even after an error, a 10-second cooldown applies. Wait for the countdown and try again. If the error repeats, contact the facility. ### Q: Both QR code and PIN code are showing — which should I use? The facility owner has enabled both. Use whichever is more convenient for the door you are trying to open. --- ## Related Pages - [About QR Code Expiration](key-expiration.md) - [Check-In Help](guest-checkin.md) - [Lock Connection](lock-connection.md) - [Check-in Configuration](checkin-config-form.md)