# The Handy Channel API v1 A channel lets you reach one or more devices through a single reference. Send a supported command once, and the channel forwards it to its active subscribers. This is multicast control. Use the Channel API to create the channel and manage its subscribers, then send commands through the [Handy REST API v3](https://links.handyfeeling.com/docs-handy-rest-api-v3), using the channel reference where a device connection key would normally go. A channel also supports device pairing. When a subscriber is configured as an event source, changes made through its physical controls can propagate through the channel to the other active subscribers. Several devices can be event sources, allowing them to influence one another. These features are useful for shared control sessions and live broadcasts. Start with a small channel and session-based subscribers. You can add pairing, persistence, and delivery delays once the basic flow is working. Channel API v1 is the current public version. Device subscribers need compatible firmware v4. Its production base URL is: ```text https://www.handyfeeling.com/api/channel/v1 ``` Apply the [device firmware policy](https://links.handyfeeling.com/docs-handy-rest-api-v3-fw3) to each participating device. If the server reports `UPDATE_REQUIRED`, stop device interaction and direct that participant to the firmware updater. A channel-level response does not replace checking the actual device. Use the [agent reference](https://links.handyfeeling.com/docs-channel-api-v1-agents) for the complete endpoint index and the [OpenAPI specification](https://links.handyfeeling.com/spec-channel-api-v1) for request and response schemas. Open an endpoint panel to try a request. Select **Authorize** inside that panel and use the credential described for its operation, then **Try it out** and **Execute**. **Settings** selects the API server and lets you hide inline examples in favor of the full Swagger UI. ## Contents - [Keep the identifiers and credentials distinct](#keep-the-identifiers-and-credentials-distinct) - [Create a channel](#create-a-channel) - [Add a device](#add-a-device) - [Send commands to the group](#send-commands-to-the-group) - [Single-device alias responses](#single-device-alias-responses) - [Choose how long membership lasts](#choose-how-long-membership-lasts) - [Pair devices through their controls](#pair-devices-through-their-controls) - [Adjust delivery delay](#adjust-delivery-delay) - [Manage subscribers](#manage-subscribers) - [Listen for channel events](#listen-for-channel-events) - [List channels and subscriptions](#list-channels-and-subscriptions) - [End the session](#end-the-session) ## Keep the identifiers and credentials distinct Follow [Developer access](https://links.handyfeeling.com/docs-guide-developer-access) to create your account and obtain an Application ID (`application_id`) or Authentication Key (`authentication_key`) for the API. Keep Authentication Keys server-side. Use the credential and header required by each operation below. The channel returns several values with different jobs. Keeping those jobs separate makes the rest of the API easier to follow. | Value | Purpose | | --- | --- | | API credential for channel creation | Creates a channel. Send it in `X-Api-Key`; the `apikey` query alternative is also supported. | | Channel ID (`channel_id`) | Identifies the channel in Channel API paths and its SSE URL. | | Channel reference (`channel_ref`) | Routes supported Handy REST commands to the group, with the `chref:` prefix. | | Channel editor key (`channel_key`) | Gives editor access to channel details, subscribers, and closure. Send it in `X-Api-Key` or `apikey`. | | Subscriber key (`subscriber_key`) | Lets someone add a subscriber. Send it in `X-Api-Key` or `apikey`. | | Device connection key | Identifies the device when joining. Use `X-Connection-Key` for device subscription listing and the explicit leave-all operation. | | Subscriber ID (`subscriber_id`) | Identifies one membership within a channel. | | User authentication credential | Lists the user's channels through `X-Auth-Key`; separate from the creation, editor, and join credentials. | Creation, editing, and joining use different credentials even though they share the `X-Api-Key` header name. Choose the credential required by the particular operation. Handy REST requests also require their own Handy REST authentication. This contract does not define Channel client-token issuance. Use the operation-specific credentials above. Share `channel_key` only with editors. Share `subscriber_key` with people who may join. Treat `channel_ref` as a control capability: someone who knows it can address the channel through supported Handy REST endpoints with the required Handy REST credentials. Channel lifecycle SSE needs only `channel_id`, so distribute that identifier with its event visibility in mind. ## Create a channel Give the channel a name and description that participants can recognize. The request body is required; the name and description are optional fields. Replace the placeholders in each example with your own values. These are illustrative requests. ```bash curl --silent --show-error --fail-with-body \ --request POST \ --header 'X-Api-Key: REPLACE_WITH_CHANNEL_API_CREDENTIAL' \ --header 'Content-Type: application/json' \ --data '{"name":"Shared session","description":"A small group session","settings":{"offset":0,"device_events":false}}' \ 'https://www.handyfeeling.com/api/channel/v1/channels' ``` [Open channel creation in Swagger UI](https://links.handyfeeling.com/swagger-channel-api-v1-create). A successful creation returns HTTP `200` and a `Channel` object. Save its `channel_id`, `channel_ref`, `channel_key`, and `subscriber_key`; later requests use the returned values. Entity responses are direct objects; collection responses have the shapes described in [List channels and subscriptions](#list-channels-and-subscriptions). The channel's `settings.offset` defaults to `0` milliseconds. Its `settings.device_events` defaults to false and controls whether the separate Handy REST SSE connection can receive device events for channel members. Read the channel later with GET `/channels/{channelId}`, using its editor key. [Open channel details in Swagger UI](https://links.handyfeeling.com/swagger-channel-api-v1#/Channels/getChannel). Handy REST `GET /info` does not support Channel v1 references: it returns HTTP `200` with `error.name: NOT_SUPPORTED` (`141008`). Use individual device keys for firmware and hardware information. ## Add a device A device can belong to several channels. For each new membership, `connection_key` is required in the JSON body; `settings` is optional. Authenticate with the channel's `subscriber_key`. ```bash curl --silent --show-error --fail-with-body \ --request POST \ --header 'X-Api-Key: REPLACE_WITH_SUBSCRIBER_KEY' \ --header 'Content-Type: application/json' \ --data '{"connection_key":"REPLACE_WITH_DEVICE_CONNECTION_KEY","settings":{"type":"session","event_source":false}}' \ 'https://www.handyfeeling.com/api/channel/v1/channels/REPLACE_WITH_CHANNEL_ID/subscribers' ``` [Open subscriber creation in Swagger UI](https://links.handyfeeling.com/swagger-channel-api-v1-subscriber-create). This example omits the subscriber offset so it follows the channel's default delay, including later changes. The returned settings represent this choice as `offset: -1`. Set `settings.offset` to `0` explicitly when the subscriber should receive commands without that delay. The response is HTTP `200` with a `Subscriber` object. Keep its `subscriber_id` and `channel_id` so an editor can manage that membership later. An `active` subscriber is receiving channel data. An `inactive` subscriber is not receiving data, for example while offline. A `closed` subscription must be created again to participate. For a participant signup flow, give the participant the `channel_id` and `subscriber_key`, and let their client submit their own device key. This avoids requiring the channel creator to collect every participant's connection key. The editor credential is unnecessary for joining. ## Send commands to the group The Channel API manages the group. Movement commands go to supported Handy REST endpoints using: ```text X-Connection-Key: chref:REPLACE_WITH_CHANNEL_REF ``` Use `channel_ref` here, with the prefix exactly once. Continue using the returned `channel_id` in Channel API paths. For example, this reads the group's HAMP state through Handy REST: ```bash curl --silent --show-error --fail-with-body \ --header 'X-Api-Key: REPLACE_WITH_HANDY_REST_APPLICATION_ID' \ --header 'X-Connection-Key: chref:REPLACE_WITH_CHANNEL_REF' \ 'https://www.handyfeeling.com/api/handy-rest/v3/hamp/state' ``` Channel-reference support is defined per Handy REST method and path. Supported operations include mode reads/selection, HAMP controls, HVP controls, and global slider-stroke reads/updates. Check the [compatibility summary](https://links.handyfeeling.com/docs-channel-api-v1-agents#handy-rest-multicast-operations) and the Handy REST endpoint index before using `chref:`. A single subscriber or alias routing does not make every endpoint channel-compatible. For example, this request goes to Handy REST v3: ```http GET /api/handy-rest/v3/info X-Connection-Key: chref:REPLACE_WITH_CHANNEL_REF ``` It returns HTTP `200` with an operation-compatibility error: ```json {"error":{"code":141008,"name":"NOT_SUPPORTED","message":"Not supported","connected":true,"data":""}} ``` Use an individual device key for `/info`, and inspect the response body even when HTTP status is `200`. This response does not describe the compatibility of other Handy REST endpoints. Channel state uses the same units as Handy REST commands: | Value | Unit | | --- | --- | | Global and HAMP stroke `min`/`max` | Relative numbers from `0` through `1`, inclusive. | | HAMP `velocity` | Number from `0` through `1` within the configured speed range. | | HVP `amplitude` and slider `position` | Relative numbers from `0` through `1`, inclusive. | | HVP `frequency` | Hz, from `0` through `10000`. | For example, `0.5` represents 50% of a relative range. HAMP stroke limits apply within the global slider range, just as they do for an individual device. The response retains the Handy REST endpoint's usual format, but represents one channel-level response even if the group has many subscribers. Normal multicast forwarding returns once the channel accepts the data for forwarding. It does not wait for each subscriber's acknowledgement. A successful group response therefore does not confirm that every device received or executed the command. Read an individual device when you need its own state. With ordinary multicast routing, `GET /connected` addressed through `chref:` tells you whether the channel is open. It is not a count or connectivity check for all subscribers. Read `GET /info` with each participant's actual device key when checking firmware or hardware. A Channel v1 reference cannot provide that information. ## Single-device alias responses V1 also has a single-device alias mode. When this mode is enabled and the channel has exactly one subscriber, its `chref:` reference acts as a connection-key alias for that device. Supported Handy REST requests return the device's actual response, rather than the ordinary channel-level acknowledgement. The response format still belongs to the selected Handy REST endpoint. The difference is its source: normal multicast acknowledges forwarding, while alias mode returns a response from the device. Check the endpoint's channel-reference support in either case. `GET /info` remains unsupported through a Channel v1 reference, including with one subscriber. Alias behavior does not establish support for every Handy REST endpoint. ## Choose how long membership lasts Set `settings.type` when adding a subscriber: | Type | Membership ends when | | --- | --- | | `session` — default | The device disconnects, or the subscriber or channel closes. | | `connection_key` | The device connection key changes, or the subscriber or channel closes. | | `device` | The subscriber or channel closes. | Use `session` for a temporary shared session. Choose a longer-lived type when membership should survive a disconnect, and provide a way for the participant to leave. Persistence describes membership lifetime; it does not mean an offline device is receiving commands. ## Pair devices through their controls Set a subscriber's `event_source` to true during creation to let physical device controls affect the channel. Changes to stroke, speed, or vibration initiated by that device's buttons can then be forwarded to the other subscribers. A channel can have several event sources. If all participating devices are event sources, each can influence the group through its controls. This is the channel's device-pairing use case. `event_source` and channel `device_events` do different jobs. The former lets a subscriber contribute control-state changes. The latter enables monitoring device events through Handy REST SSE. Neither flag is needed simply to receive Channel API lifecycle events. ## Adjust delivery delay Supply nonnegative whole numbers in milliseconds when setting a delay. No upper limit is currently enforced. For example, `1000` delays forwarding by one second. A new subscriber follows the channel's current offset when its own offset is omitted. If the channel default is `1000`, omitting the subscriber offset gives a one-second delay; explicitly sending `offset: 0` gives no delivery delay. A subscriber's explicit offset is its complete delivery delay. With a channel default of `1000` and a subscriber offset of `500`, that subscriber's delay is `500` milliseconds. Returned subscriber settings use `-1` to indicate dynamic inheritance. If the channel default changes, these subscribers follow the new delay. The sentinel is a response value; sending `offset: -1` in a create or update request is not supported by v1. This is useful when device commands travel faster than a live video stream. Start with an estimate of the video delay, then let each participant adjust their subscriber offset for their own viewing setup. An offset is a delivery delay; precise external synchronization still depends on the selected movement protocol and its timing requirements. Update the channel's settings with an editor key: ```bash curl --silent --show-error --fail-with-body \ --request PUT \ --header 'X-Api-Key: REPLACE_WITH_CHANNEL_KEY' \ --header 'Content-Type: application/json' \ --data '{"settings":{"offset":1000}}' \ 'https://www.handyfeeling.com/api/channel/v1/channels/REPLACE_WITH_CHANNEL_ID' ``` Changing the channel default also affects existing subscribers whose returned offset is `-1`. If the default changes from `1000` to `2000`, those subscribers now use `2000` milliseconds. A subscriber with an explicit `500` continues using `500`. [Open channel updates in Swagger UI](https://links.handyfeeling.com/swagger-channel-api-v1#/Channels/updateChannel). ## Manage subscribers Use `channel_key` to read, update, or close an individual membership. To update a membership, send a `settings` object using `SubscriberSettings`: `offset`, `event_source`, `type`, and `hw_model_no`. The response is the updated `Subscriber` object, including its settings. The `device_events` flag belongs to channel settings and is configured through the channel endpoint. For example, an editor can change a participant's delivery delay: ```bash curl --silent --show-error --fail-with-body \ --request PUT \ --header 'X-Api-Key: REPLACE_WITH_CHANNEL_KEY' \ --header 'Content-Type: application/json' \ --data '{"settings":{"offset":1500}}' \ 'https://www.handyfeeling.com/api/channel/v1/channels/REPLACE_WITH_CHANNEL_ID/subscribers/REPLACE_WITH_SUBSCRIBER_ID' ``` [Open subscriber updates in Swagger UI](https://links.handyfeeling.com/swagger-channel-api-v1-subscriber-update). Use GET on that same path to read a membership. GET `/channels/{channelId}/subscribers`, authenticated with `channel_key`, lists channel subscribers. It defaults to non-closed subscribers; `status=active,inactive` explicitly selects those two states. [Open membership details in Swagger UI](https://links.handyfeeling.com/swagger-channel-api-v1#/Channels/getSubscriber). ## Listen for channel events Channel lifecycle events use the Channel API's SSE endpoint: ```text https://www.handyfeeling.com/api/channel/v1/channels/REPLACE_WITH_CHANNEL_ID/sse ``` This endpoint does not require a token or custom authentication header. Native browser `EventSource` can open it directly. An optional `events` query parameter is a comma-separated filter; omitting it subscribes to all events. | Event | Meaning | | --- | --- | | `channel_state` | Current channel state, on connection and state changes. | | `channel_closed` | The channel and its remaining subscribers have closed. | | `subscriber_added` | A member joined. | | `subscriber_closed` | A membership ended. | | `subscriber_inactive` | A member became inactive. | | `subscriber_activated` | A member became active. | For a membership that survives disconnection, `subscriber_inactive` reports the device going offline and `subscriber_activated` reports its return. These payloads identify the membership and can include its settings snapshot. Each SSE frame has an `id`, an event name, and a JSON payload. The payload contains the event data directly: ```text id: EXAMPLE_EVENT_ID event: subscriber_added data: {"channel_id":"EXAMPLE_CHANNEL_ID","subscriber_id":"EXAMPLE_SUBSCRIBER_ID","settings":{"offset":-1,"type":"session","event_source":false}} ``` Fetch the current subscriber list separately; the SSE connection does not supply initial subscriber snapshots or settings-update notifications. Use the update response or read a membership when you need its current settings, and reconcile the list after reconnecting. Register handlers for the named events: ```javascript const events = new EventSource( 'https://www.handyfeeling.com/api/channel/v1/channels/REPLACE_WITH_CHANNEL_ID/sse' ); function handle(event) { const data = JSON.parse(event.data); console.log(event.type, event.lastEventId, data); if (event.type === 'channel_closed') events.close(); } for (const type of [ 'channel_state', 'channel_closed', 'subscriber_added', 'subscriber_closed', 'subscriber_inactive', 'subscriber_activated' ]) { events.addEventListener(type, handle); } // Call events.close() when this view or session is finished. ``` For device-level events, use the separate [Handy REST SSE endpoint](https://links.handyfeeling.com/docs-handy-rest-api-v3#listen-for-device-events), with its Handy REST credential, channel reference, and channel `device_events=true`. A Channel API lifecycle subscription does not replace that device-event connection. ```mermaid sequenceDiagram participant C as Channel creator participant A as Channel API participant P as Participant participant R as Handy REST v3 participant D as Active devices C->>A: Create channel with API credential A-->>C: Channel ID, reference, editor key, join key C-->>P: Share channel ID and join key P->>A: Join with own device connection key A-->>P: Subscriber ID and settings C->>R: Supported command with chref and REST credential R->>D: Forward to active subscribers R-->>C: One channel-level response A-->>C: Channel lifecycle events over Channel SSE ``` ## List channels and subscriptions GET `/channels` lists a user's channels with the user-authentication credential in `X-Auth-Key`. The default status filter selects active channels. Its response has a top-level `data` array and pagination fields when applicable. [Open user-channel listing in Swagger UI](https://links.handyfeeling.com/swagger-channel-api-v1#/Channels/getUserChannels). GET `/channels/{channelId}/subscribers` uses the channel editor key and wraps its list in `result`: ```json {"result":{"cursor":"NEXT_CURSOR","data":[]}} ``` Read subscriber data from `result.data` and pagination fields from the same `result` object. Pagination metadata may include `count`, `offset`, and `cursor`. [Open the subscriber list in Swagger UI](https://links.handyfeeling.com/swagger-channel-api-v1#/Channels/getSubscribers). For those lists, `limit` is `1–1000`, default `100`; `offset` starts at `0`. Supply the returned cursor for another page when available. A supplied cursor takes precedence over offset. Pagination offset is an element index; it is unrelated to the millisecond delivery delay. GET `/subscriptions` uses the device connection key in `X-Connection-Key` and returns a direct array of non-closed memberships. The device must be online for this operation to return subscriptions. An empty result while offline is not proof that it has no memberships. [Open device subscriptions in Swagger UI](https://links.handyfeeling.com/swagger-channel-api-v1#/Subscriptions/getSubscriptions). ## End the session End movement with the appropriate Handy REST stop command while the channel is still open. Then close the routing resources you no longer need. - PUT `/channels/{channelId}/subscribers/{subscriberId}/close` closes one membership. Use the editor key. - PUT `/channels/{channelId}/close` closes the channel and all remaining non-closed memberships. Use the editor key. The closed channel accepts neither commands nor new subscribers. - GET `/subscriptions/close` closes **all non-closed memberships** for the specified online device. Although its HTTP method is GET, this operation changes state; use it only for an explicit leave-all action. For example, close a channel after finishing its controls: ```bash curl --silent --show-error --fail-with-body \ --request PUT \ --header 'X-Api-Key: REPLACE_WITH_CHANNEL_KEY' \ 'https://www.handyfeeling.com/api/channel/v1/channels/REPLACE_WITH_CHANNEL_ID/close' ``` [Open channel closure in Swagger UI](https://links.handyfeeling.com/swagger-channel-api-v1-close). To close only one membership, use its channel and subscriber IDs with the editor key: [Open membership closure in Swagger UI](https://links.handyfeeling.com/swagger-channel-api-v1#/Channels/closeSubscriber). Use the leave-all operation only when the participant explicitly chooses to leave every non-closed membership for that device: [Open device leave-all in Swagger UI](https://links.handyfeeling.com/swagger-channel-api-v1#/Subscriptions/closeSubscriptions). Closing a channel or an individual subscriber returns HTTP `200` with no response body. Do not try to parse JSON from these responses. Use a separate GET if you need the resulting resource state. Channels are also closed automatically when no subscriber has been active for the preceding six hours. Plan explicit closure for your application flow rather than using stale-channel cleanup as its session timer. For complete contracts, see the [agent reference](https://links.handyfeeling.com/docs-channel-api-v1-agents), [OpenAPI specification](https://links.handyfeeling.com/spec-channel-api-v1), and [Swagger UI](https://links.handyfeeling.com/swagger-channel-api-v1).