Home Assistant WebSocket connection and node overview

Why this chapter matters

Home Assistant nodes are much more than an action-invocation button. The pinned package registers 32 NodeTypes: some receive events, some query the cache, some call APIs, and some create companion entities in HA. It also includes config nodes for shared connections and deprecated nodes retained for compatibility. Treating them all alike can lead you to mistake a read for a trigger, use a config node as a flow step, or expose a high-risk API node to untrusted input.

This chapter uses Community Add-on 22.0.1 as its baseline. Its node-red/package.json pins the bundled Node-RED 5.0.2 and node-red-contrib-home-assistant-websocket 0.80.3. The Add-on manifest’s homeassistant_api: true grants an authorization capability, while the package README explicitly offers Add-on users the “I use the Home Assistant Add-on” connection mode. Together, these define the preconfigured connection path.

Core concepts

• A Server config is shared configuration: Its persisted type is server. It stores the connection mode and common settings and is referenced by multiple HA nodes; it is not an ordinary processing step with an input and output.
• An executable node runs in a flow: It may emit output in response to an HA event, query data when a msg arrives, or produce an external side effect. Each type has its own trigger timing, output-property behavior, and error contract.
• An entity node exposes a companion entity: It lets Node-RED present a binary sensor, button, number, select, sensor, switch, text entity, or time entity in HA. This is not the same as querying an existing entity.
• A config node provides shared settings: Server, Device Config, and Entity Config are the 3 actual config nodes. Update Config is instead an executable utility with one input and one output; it modifies companion metadata and is not a config node.
• Deprecated means compatibility only: The old generic Entity persisted type, ha-entity, remains registered, but new flows should use a specific entity node. Keep a backup and compare every field before migrating.

The current UI term is Action. Legacy flows and documentation may call it Call Service; use that former name only to identify existing material. In 0.80.3, the NodeType key is Action, but the persisted type remains api-call-service. Do not manually change an exported JSON type to action, and do not recreate credentials merely because the displayed name changed.

Confirm the Add-on’s preconfigured connection

1. Confirm the baseline and create a backup.

   Check the version on the Add-on information page, then back up your flows and credentials. Do not call it “Node-RED 22.0.1”; the accurate description is Add-on 22.0.1 with Node-RED 5.0.2 bundled.

2. Add a read-only node.

   Begin with Current State or another node that performs a query only after receiving a manual message. For detailed Current State configuration and missing-value handling, see Chapter 10. Do not use Action, Fire Event, API, Webhook, or a companion switch for your first connection test.

3. Select the existing Server config.

   In the node’s Server field, select only the existing Server config preconfigured by the Add-on. Do not add another config, edit the connection, or enter a token. If the preconfigured config is absent from the list, stop immediately and follow this chapter’s troubleshooting guidance; do not create a substitute config yourself.

4. Complete the configuration with a placeholder.

   If the tutorial screen requires an entity, use a read-only entity approved specifically for testing in your environment; replace it with sensor.example_temperature in any record or documentation. Do not disclose entity, device, area, tag, zone, or webhook IDs.

5. Deploy and observe the status.

   Use the narrowest Deploy scope, then inspect the node status and Add-on log for connection information. Configure Debug to emit only the necessary fields, never the complete config, headers, or HA state attributes.

6. Validate failure paths.

   Without changing credentials, test conditions such as a missing entity and unknown or unavailable data. Add Catch and Status nodes to confirm that failures cannot reach any node with side effects.

The Add-on path should directly reuse the existing preconfigured Server config; check its references first. If it does not exist, stop this chapter’s procedure here—do not establish a second connection. Deleting or changing a shared config affects every node that references it, making this the most common operational risk at the config/runtime boundary.

Add-on connection, permission, and privacy boundaries

The Add-on 22.0.1 manifest declares homeassistant_api: true, and the Add-on’s direct dependencies pin the package to 0.80.3. This demonstrates that the image contains the compatible package and has access to the HA Core API. It does not mean that every imported flow is safe or that every third-party node automatically receives least-privilege access. Node-RED flows and additional packages operate within the trusted execution boundary and must still be reviewed before import.

The Server editor’s connection settings include Add-on mode, connection delay, base URL and access token (for non-Add-on connections), certificate options, and heartbeat. It also includes settings for HA booleans, global-context exposure, the autocomplete cache, and selector/status UI behavior. Do not disable certificate validation for troubleshooting, and do not export a base URL, access token, or complete config into public material.

Multiple nodes—including Current State, Events: state, and Action—reference the Server config. Changing it is therefore a shared change, not one confined to the current dialog. Before making a change, inspect the config node’s references; afterward, review the actual scope shown under Modified Nodes/Flows. Connection delay and heartbeat are connection-management settings, not application-level retries, and they cannot guarantee that a particular Action will succeed.

The HA server cache lets nodes such as Current State and Get Entities query state, but the presence of cached data does not guarantee freshness. Explicitly handle disconnections, startup, unknown, unavailable, and the addition or removal of entities. Apply an allowlist when outputting state attributes, retaining only the fields needed for the decision.

Node classification and a four-step learning path

You do not need to memorize every node first. Learn them in this sequence: Events: state (Chapter 9) for events; Current State and Get Entities (Chapter 10) for state queries; Action (Chapter 11) for executing actions; and the remaining event and time nodes (Chapter 12). Then continue to the practical project in Chapter 13 and companion entities in Chapter 14.

Version 0.80.3 provides 32 NodeTypes: 19 in home_assistant, 9 in home_assistant_entities (8 companion entity types plus the executable Update Config utility), 3 in config, and 1 deprecated type.

Use this matrix for selection and reference. You do not need to add all 32 nodes to a flow; choose the appropriate category, then continue to the corresponding chapter for implementation.

Responsibility boundaries between Server/config and executable nodes

An executable node acts after the runtime receives a msg or HA event; a config node provides shared objects and metadata. A Server config may be invisible on the canvas even though more than a dozen nodes reference it. “Deleting an invisible setting” can therefore disconnect an entire group of nodes, while editing an Action does not automatically change the Server.

Interpret the current Action node UI in terms of action, target, and data: the target selects entities, devices, or areas, while data supplies parameters for that action. The response depends on the HA action and is not guaranteed to appear in msg.payload. Current State, Get Entities, Action, and other nodes can also configure their output property; never assume that a node always overwrites the payload.

Action and Current State provide a Block Input Overrides boundary, but you cannot generalize it to every node. Get Entities can accept msg.payload.* overrides for its rules and output and has no equivalent universal switch. If input originates from HTTP, MQTT, or a webhook, first use Change or Switch nodes to remove prohibited fields and enforce an allowlist. Never pass an unverified external msg directly to the API, Fire Event, or Action node; a companion switch or button; or any other surface with side effects.

A companion entity is an entity that Node-RED provides to HA. Binary Sensor and Sensor primarily output state; Button can trigger a flow when pressed in HA; Number, Select, Text, and Time accept constrained values; and Switch has get, set, and listen semantics. Every type requires policies for availability, input validation, uniqueness, and removal or migration. Chapter 14 provides a detailed implementation; this chapter does not create a real companion entity.

Three requirement floors and their version boundaries

The 0.80.3 README lists these user prerequisites: Home Assistant 2024.3+, Node-RED 3.1.1+, and Node.js 18.2.0+. The Node and Node-RED floors can also be verified in the package metadata. These are the compatibility requirements that the package declares to users.

Add-on 22.0.1’s config.yaml separately specifies homeassistant: 2023.3.0. This is the Supervisor’s Add-on installation floor; it does not replace the package README’s Home Assistant 2024.3+ prerequisite. The package’s src/const.ts also contains the internal constant HA_MIN_VERSION = '2023.12'; it likewise cannot lower the user-facing 2024.3+ floor. These three numbers belong to different layers and must be reported separately during troubleshooting.

Before upgrading any layer, create a backup, review release notes and migrations, and validate the change in a test flow with side-effecting nodes disabled. Legacy Entity nodes, the persisted Action type, output properties, and unknown/unavailable/null old and new states are all common migration hazards. Do not perform a direct search and replace on flow JSON types, and do not use a new palette label as a persisted type.

All entity, device, area, tag, zone, and webhook IDs are environment-specific data; webhook URLs and IDs are particularly sensitive because they are entry points. Documentation and issue reports should use placeholders such as sensor.example_temperature and remove access tokens, headers, locations, calendar contents, and state attributes. Never copy a fictional ID into production and bypass the live environment’s allowlist.

Troubleshooting

• The Add-on’s preconfigured Server config is missing: Stop this chapter’s procedure immediately. Confirm that you opened the correct Add-on 22.0.1 editor and that initialization and the Add-on log are normal, then inspect the installation against the pinned Add-on documentation. Do not add a Server config or create or paste a token for troubleshooting.
• Only one node produces no output: Check that node’s trigger/input mode, entity selector, output property, and handling of unknown/unavailable. Isolate it with a manual Inject and a Debug node limited to required fields; do not change the shared credentials.
• A legacy Entity node appears after import: It is the deprecated ha-entity type. Back up the flow and read the migration documentation before mapping it to a specific companion entity; do not directly edit the JSON type.
• You cannot find the JSON type for Action: The current palette label is Action, but the persisted type remains api-call-service. This is expected compatibility behavior. Do not change it to the nonexistent action type.
• A version above the installation floor still appears incompatible: Do not confuse the Add-on’s HA 2023.3.0 floor with the package’s HA 2024.3+ prerequisite. Record all five layers: Add-on, Node-RED, HA WS, HA, and Node.
• Debug discloses IDs or attributes: Immediately disable full-message Debug output and clean the sidebar, logs, and exports. Substitute placeholders before opening a public issue. If credentials may have been exposed, rotate them through the incident-response process and do not transmit their values to anyone else.

Pinned sources

• Add-on 22.0.1 pinned commit bcfd5b8: node-red/config.yaml and node-red/package.json.
• HA WebSocket 0.80.3 pinned commit 2cbbb69: README.md, package.json, src/const.ts, src/index.ts, and src/nodes.
• Official HA WebSocket user guide.
• Pinned official documentation for Add-on 22.0.1.

Before selecting a node, determine whether it handles reads, events, external side effects, shared configuration, or companion entities. Then follow the learning path above to the relevant chapter; similar names are no substitute for verifying behavior.

FAQ