# homeassistant-ws

> Client for Homeassistant's websocket API

Latest version **0.2.5** (published 2025-09-08) · MIT license · 0 weekly downloads

## Install

```sh
npm install homeassistant-ws
pnpm add homeassistant-ws
yarn add homeassistant-ws
bun add homeassistant-ws
```

## Health

**Score 30/100 (F)** — status: maintenance-mode.

Positive: has types; no vulnerabilities.

Warnings: low downloads; no esm support; pre 1.0.

Negative: stale; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.2.5 |
| Published | 2025-09-08 |
| First published | 2020-04-26 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | CommonJS |
| Dependencies | 2 |
| Unpacked size | 25.2 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 18 |
| Maintainers | filp |
| Keywords | homeassistant, websocket, hass, ha, smart, home, api, hassio |

## Links

- npm: https://www.npmjs.com/package/homeassistant-ws
- Repository: https://github.com/filp/homeassistant-ws
- Issues: https://github.com/filp/homeassistant-ws/issues
- npm.io page: https://npm.io/package/homeassistant-ws

## Dependencies (2)

- [ws](https://npm.io/package/ws.md) ^8.0.0
- [isomorphic-ws](https://npm.io/package/isomorphic-ws.md) ^4.0.1

## Alternatives

- [d3-force-3d](https://npm.io/package/d3-force-3d.md) — 1.0M weekly downloads
- [ng2-charts](https://npm.io/package/ng2-charts.md) — 486.8K weekly downloads
- [@arcgis/core](https://npm.io/package/@arcgis/core.md) — 257.8K weekly downloads
- [react-sparklines](https://npm.io/package/react-sparklines.md) — 249.3K weekly downloads
- [react-native-gifted-charts](https://npm.io/package/react-native-gifted-charts.md) — 182.3K weekly downloads

## Recent versions

- 0.2.5 (latest) — 2025-09-08
- 0.2.4 — 2025-09-08
- 0.2.3 — 2024-08-24
- 0.2.2 — 2021-07-29
- 0.2.1 — 2021-05-21
- 0.2.0 — 2021-05-21
- 0.1.4 — 2021-05-10
- 0.1.3 — 2021-03-11
- 0.1.2 — 2020-05-06
- 0.1.1 — 2020-04-29
- 0.1.0 — 2020-04-26

## README

# homeassistant-ws

[![npm](https://img.shields.io/npm/v/homeassistant-ws?color=%23ff11dd&style=flat-square)](https://www.npmjs.com/package/homeassistant-ws)
[![GitHub](https://img.shields.io/github/license/filp/homeassistant-ws?style=flat-square)](https://github.com/filp/homeassistant-ws/blob/master/LICENSE.md)

Minimalist client library for [Homeassistant's Websocket API](https://developers.home-assistant.io/docs/external_api_websocket). Works in node, and also in the browser.

---

## Installation:

Using `npm`:

```shell
$ npm i --save homeassistant-ws
```

Import it in your project:

```js
import hass from 'homeassistant-ws';

async function main() {
  // Assuming hass running in `localhost`, under the default `8321` port:
  const client = await hass({
    token: 'my-secret-token',
  });
}
```

Tokens are available from your profile page under the Homeassistant UI. For documentation on the authentication API, see [the official HA documentation](https://developers.home-assistant.io/docs/auth_api/).

## Configuration options

The following properties (shown with their defaults) can be passed to the constructor. All are **optional**.

```js
hass({
  protocol: 'ws',
  host: 'localhost',
  port: 8123,
  path: '/api/websocket',

  // Must be set if HA expects authentication:
  token: null,

  // Used to serialize outgoing messages:
  messageSerializer: (outgoingMessage) => JSON.stringify(outgoingMessage),

  // Used to parse incoming messages. Receives the entire Websocket message object:
  messageParser: (incomingMessage) => JSON.parse(incomingMessage.data),

  // Should return a WebSocket instance
  ws: (opts) => {
    return new WebSocket(
      `${opts.protocol}://${opts.host}:${opts.port}${opts.path}`
    );
  },
});
```

## Example

The following example includes all available methods. For more details on available Homeassistant event types, states, etc. see the [official Websocket API](https://developers.home-assistant.io/docs/external_api_websocket)

```js
import hass from 'hass';

async function main() {
  // Establishes a connection, and authenticates if necessary:
  const client = await hass({ token: 'my-token' });

  // Get a list of all available states, panels or services:
  await client.getStates();
  await client.getServices();
  await client.getPanels();

  // Get hass configuration:
  await client.getConfig();

  // Get a Buffer containing the current thumbnail for the given media player
  await client.getMediaPlayerThumbnail('media_player.my_player');
  // { content_type: 'image/jpeg', content: Buffer<...>}

  // Get a Buffer containing a thumbnail for the given camera
  await client.getCameraThumbnail('camera.front_yard');
  // { content_type: 'image/jpeg', content: Buffer<...>}

  // Call a service, by its domain and name. The third argument is optional.
  await client.callService('lights', 'turn_on', {
    entity_id: 'light.my_light',
  });

  // Listen for all HASS events - the 'message' event is a homeassistant-ws event triggered for
  // all messages received through the websocket connection with HASS:
  //
  // See https://developers.home-assistant.io/docs/api/websocket/ for details on HASS events:
  client.on('message', (rawMessageData) => {
    console.log(rawMessageData);
  });

  // Listen only for state changes:
  client.on('state_changed', (stateChangedEvent) => {
    console.log(stateChangedEvent.data.new_state.state);
  });
}
```

---
_Source: https://npm.io/package/homeassistant-ws · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._