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.

Automatic directory filling from photos

Use Enrich to fill the visitor directory (display_name on apartment entities) from photos of intercom panels or post office box banks. Visitors see these names in the public intercom directory (GET …/targets).

In-app flow (recommended)

1. Open Access → building → Virtual Intercom.
2. Click Enrich.
3. Upload one or more photos (camera or gallery). Photos are resized on your device before upload.
4. Click Analyze. OpenApp sends the images to Google (Gemini API) and returns structured apartment names.
5. Review the table (rename existing units or add new rows), edit names if needed, then Commit.

Requirements: entities:update permission; a directory device on the integration. In cloud zones, operators must set OPENAPP_GEMINI_API_KEY in AWS Secrets Manager (openapp/<workspace>/backend/gemini_api_key) and roll the backend service.

Privacy: OpenApp does not store uploaded photos. They are processed by Google for analysis only; see Google Gemini API privacy for provider terms.

Scope: Enrich updates display names (and can create apartment rows). It does not set floors, residents, or call routing.

Manual JSON fallback

If photo analysis is unavailable, expand Paste JSON manually in the Enrich modal and paste or upload JSON in the same shape as before ({ "apartments": [ … ] }). That path does not send images through OpenApp.

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