Listen to events
GET/userSession/websocket
Base URL: https://api.tinkermode.com
Establish a WebSocket connection and listen for events. Any non-WebSocket requests will be rejected.
Once the connection is established, the client can expect incoming messages in the form of Event JSON objects.
Use one of the homeId, deviceId, or entityId query parameter to limit what events to be sent through the connection.
If both homeId and deviceId parameters are present at the same time, only deviceId will take effect.
Also, if both deviceId and entityId parameters are present at the same time, only entityId will take effect.
One query parameter is required if the project is configured to use the permission-based access control.
To receive home events with the homeId parameter, the user requires read permission for home events of the home.
To receive device events with the deviceId parameter, the user requires read permission for the device.
To receive entity events with the entityId parameter, the user requires read permission for entity events of the entity.
Since not all WebSocket client implementations allow you to set the Authorization HTTP header, you can pass the user API key as the authToken query parameter.
This API call is not allowed for BYOU projects.
Authentication
Send an Authorization header of the form ModeCloud <AUTH_CODE>.
Must contain API key of a user.
Query parameters
| Name | Type | Required | Constraints | Description |
|---|---|---|---|---|
authToken | string | No | User API key. Needed only if the Authorization header cannot be set. | |
deviceId | integer | No | If this parameter is present, only events from the specified device will be sent through this WebSocket connection. This parameter can be used multiple times to capture events from multiple devices. | |
entityId | string | No | If this parameter is present, only events of the entity will be sent through this WebSocket connection. This parameter can be used multiple times to capture events for multiple entities. | |
homeId | integer | No | If this parameter is present, only events for the specified home will be sent through this WebSocket connection. This parameter can be used multiple times to capture events for multiple homes. |
Responses
101 Successfully established a WebSocket connection.
401 Authorization is required to access this resource.
403 Request failed because of invalid data or denied permission.
Content type: application/json
| Property | Type | Required | Constraints | Description |
|---|---|---|---|---|
data | object | No | read-only (server-generated) | Any relevant data related to error. |
reason | string | Yes | read-only (server-generated) | Reason of error. |
404 The requested resource does not exist or is not accessible.
Content type: application/json
| Property | Type | Required | Constraints | Description |
|---|---|---|---|---|
data | object | No | read-only (server-generated) | Any relevant data related to error. |
reason | string | Yes | read-only (server-generated) | Reason of error. |
500 An unexpected error has occurred.
Content type: application/json
| Property | Type | Required | Constraints | Description |
|---|---|---|---|---|
data | object | No | read-only (server-generated) | Any relevant data related to error. |
reason | string | Yes | read-only (server-generated) | Reason of error. |
503 The service is temporarily unavailable.
Content type: application/json
| Property | Type | Required | Constraints | Description |
|---|---|---|---|---|
data | object | No | read-only (server-generated) | Any relevant data related to error. |
reason | string | Yes | read-only (server-generated) | Reason of error. |