Virtual Access

At a glance

• Product: OpenApp Virtual Access
• Manufacturer: OpenApp

Getting started

This provider does not expose integration-level actions or ops; instead, it uses devices with a kind field in their metadata to define directories, doors, and apartments. Door openers reference switch entities from other integrations (e.g. Shelly Cloud, MQTT).

1. Create an integration with provider type virtual_access and set the config. Door/light delay fields are optional overrides; if omitted, the backend uses the deploy-wide virtual access defaults.
2. Create a directory device with kind: "virtual_access_directory" in its metadata.
3. Create apartment entities under the directory device (entity_type apartment) and set their metadata. Manage them in the Virtual Intercom section (Access → building → Virtual Intercom).
4. Create portal devices with kind: "virtual_access_portal" in their metadata, link go2rtc cameras and opener entities.
5. Open the access dashboard to view cameras and open portals.

Device kinds

Kind	Purpose
virtual_access_directory	Building directory. Apartments are entities (entity_type apartment) under this device.
virtual_access_portal	A portal (door/gate/etc.) with cameras and optional openers

Directory device metadata

A virtual_access_directory device uses:

Field	Type	Description
kind	string	Must be "virtual_access_directory"

Apartments are modeled as entities under the directory device, not in device metadata. Create one entity per apartment with entity_type: "apartment" and set entity metadata (apartment_number, display_name, etc.).

Portal device metadata

A virtual_access_portal device uses the following metadata structure:

Field	Type	Description
kind	string	Must be "virtual_access_portal"
go2rtc_camera_device_ids	string[]	IDs of go2rtc camera devices for this portal
virtual_access.openers	object[]	Ordered list of opener entities. Each: { entity_id, label? }. The dashboard tries each in sequence until one succeeds (fallback).
virtual_access.open_config	object	Optional. Controls the portal-level door auto-close behavior: auto_close (bool, default true), auto_close_delay (seconds, default = integration default_door_auto_close_delay_seconds when set, otherwise the deploy-wide backend default).
virtual_access.lights	object[]	Optional. Light fixtures to turn on when the door is opened (e.g. lobby light). Each: { entity_id, label?, auto_off_config? }. Light auto-off uses auto_close/auto_close_delay in the nested config, defaulting to integration default_light_auto_off_delay_seconds when set, otherwise the deploy-wide backend default.

Example:

{
  "kind": "virtual_access_portal",
  "go2rtc_camera_device_ids": ["01HXXX...", "01HYYY..."],
  "virtual_access": {
    "openers": [
      { "entity_id": "01HZZZ...", "label": "Main Entrance" },
      { "entity_id": "01HAAA...", "label": "Backup Relay" }
    ],
    "open_config": {
      "auto_close": true,
      "auto_close_delay": 20
    },
    "lights": [
      { "entity_id": "01HBBB...", "label": "Lobby", "auto_off_config": { "auto_close": true, "auto_close_delay": 60 } }
    ]
  }
}

When a portal has openers, the access dashboard shows an Open button. Clicking it triggers switchable.open on the linked opener entities and optionally turns on configured lights.

Auto-close semantics

• virtual_access.open_config describes the portal’s own door auto-close behavior.
• If auto_close is omitted or true, OpenApp sends auto_off_seconds to the opener action using auto_close_delay, the integration’s default_door_auto_close_delay_seconds when set, or the deploy-wide backend default otherwise.
• If auto_close is false, OpenApp sends no door auto-close payload, so the portal itself does not request an automatic close.
• The dashboard’s Effective door auto-close value reflects this portal configuration, not fallback/default auto-off behavior of the linked opener integration.
• Linked opener entities can still expose their own switchable auto-off status panel, which describes the opener device itself.
• virtual_access.lights[*].auto_off_config is separate from the door config. Each light keeps its own effective auto-off behavior and status/fix alignment, and uses the integration’s default_light_auto_off_delay_seconds when set, or the deploy-wide backend default otherwise.

Enriching apartment names from photos

You can populate or enrich apartment display names using photos of intercom panels or post office boxes. Copy the prompt below, paste it into an image-capable AI tool (e.g. Gemini, ChatGPT) alongside one or more photos for the same building, then paste or upload the resulting JSON in the dashboard (Access → building → Virtual Intercom → Enrich).

Prompt to copy:

You are given one or more photos of intercom panels or post office box listings for the same building. Extract each apartment/unit identifier and the corresponding name(s) visible next to it from all images. Combine into a single list; if the same apartment appears in multiple images, merge the display_name (include all languages from each). Names may appear in multiple languages (e.g. English and Hebrew).

Output valid JSON in this exact format:
{
  "apartments": [
    { "apartment_number": <number or null>, "display_name": { "en": "...", "he": "..." } },
    { "apartment_label": { "en": "..." }, "display_name": { "en": "..." } }
  ]
}

Rules:
- Use apartment_number when the identifier is numeric (e.g. 101, 2).
- Use apartment_label when it's a letter or custom label (e.g. "A", "Ground").
- Include all visible languages in display_name.
- Preserve exact spelling. Output only valid JSON.

After pasting or uploading the JSON in the Enrich modal, you can review the merge (incoming vs existing data), edit any proposed names, and commit the changes.

Setup reference

Config

Field	Type	Required	Description	Default	Example
location	object	optional	Building location. When set, must include lat, lng, and address (LocalizedString). Optional: city, country.	—	{ "lat": 32.0, "lng": 34.8, "address": { "en": "123 Main St" } }
default_door_auto_close_delay_seconds	integer	optional	Optional per-integration override for the door auto-close delay used when a portal enables auto-close without setting an explicit delay. If omitted, the backend uses the deploy-wide virtual access default.	—	20
default_light_auto_off_delay_seconds	integer	optional	Optional per-integration override for the light auto-off delay used when a linked light enables auto-off without setting an explicit delay. If omitted, the backend uses the deploy-wide virtual access default.	—	120
floor_order	array of strings	optional	Optional ordered list of canonical floor keys for this building (`n:{floor_number}` for numeric floors, or `l:{hex}` for label-only floors—same encoding as apartment metadata). Usually edited in Access → Building (drag-and-drop). Supplied to public directory sorting when set.	—	["n:-1", "n:0", "n:1", "l:a1b2c3d4e5f67890"]

Apartment entity metadata (per apartment entity under directory device)

Field	Type	Required	Description	Default	Example
apartment_number	integer	optional	Numeric apartment/unit when not using a custom label.	—	101
apartment_label	object	optional	Apartment's display identifier when using custom label.	—	{ "en": "Warehouse", "he": "מחסן" }
display_name	object	required	LocalizedString map: { [locale: string]: string }.	—	{ "en": "Apt 101", "he": "דירה 101" }
floor_number	integer	optional	Numeric floor when not using a custom label.	—	1
floor	object	optional	Floor's display name when using custom label (e.g. Ground, 1st, Lobby).	—	{ "en": "Ground", "he": "קומת קרקע" }
image_asset_id	string	optional	S3 media asset ID for apartment image. Set via image upload in the UI.	—	01HXXX...
virtual_access	object	optional	Per-apartment access policy overrides (policy or policy_overrides).	—	{ "policy": { "allowed_actions": ["call"] } }