# Socket.io Specification

Once you've got the [HTTP Specification](/http-and-socket.io/http-specification.md) set up, you might be interested in receiving realtime events from Homey. For example, to do something when a device turns on.

While Socket.io is primarily developed for Node.js, there are many alternative clients available for other languages. Here are a few examples.

* [Python](https://python-socketio.readthedocs.io/en/latest/client.html)
* [Go](https://pkg.go.dev/github.com/zhouhui8915/go-socket.io-client)
* [Rust](https://github.com/1c3t3a/rust-socketio)
* [C#](https://github.com/doghappy/socket.io-client-csharp)

### Step 1 — Connect to Socket.io

Connect to the `localUrl`, `localUrlSecure` or `remoteUrl` of Homey Pro or Homey Cloud with only the `websocket` transport. We recommend using a `pingTimeout` of `8000ms` and `pingInterval` of `5000ms`.

### Step 2 — Authenticate with Homey

Emit an event `handshakeClient` with the following object as parameter:

```json
{
  "token": "<session token>", // The Session Token
  "homeyId": "abc..." // The ID of the Homey
}
```

As third and last parameter, provide a `callback` function with a two parameters `(error, result)` . If `error` is present, it could be a `string` with an error message or an object with the `error` and `error_description` properties.

If `result` is set, authentication was successful. Within `result`, there is a property called `namespace` , for example `/api`. This is the root namespace for Socket.io where broadcasts happen. Your client should again connect to this namespace.

### Step 3 — Subscribe to Events

To subscribe to realtime events, you need to let Homey know you are interested in these events. To do so, emit a `subscribe` event with an `uri` as second parameter. As third parameter, provide a `callback` method with an `(error, result)` pattern.

An URI could be, for example, `homey:manager:flow` to get events when a Flow gets created, updated and deleted. Another example is `homey:device:abc...` to get capability updates of a specific device.

After subscribing, bind a local event listener where the event name is the `uri`. For example, in JavaScript, this looks like `socket.on(uri, (event, data) { ... })` .

{% hint style="info" %}
To unsubscribe, emit the `unsubscribe` event with `uri` as second parameter.
{% endhint %}

Within the API reference, you can find all events that could be emitted. For example, see [ManagerFlow](https://athombv.github.io/node-homey-api/HomeyAPIV3Local.ManagerFlow.html#section-events).


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://api.developer.homey.app/http-and-socket.io/socket.io-specification.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.