<aside> ⚠️ This API is still in BETA, but the core functionality is considered stable. We will do our best to make any additional changes backward compatible. Feedback, bug reports or feature requests are welcome.

This version of the Channel API is only compatible with devices with firmware 4. Devices with an older firmware version must be upgraded before they can be added as channel subscribers.

</aside>

The Channel API manages channels and their subscribers, and offers utilities to simplify sending commands to multiple devices at the same time (multi-casting). It can also enable device pairing and provide connection-key aliases.

Channels

The Channel API lets you create and manage channels. A channel can be used to send commands to channel subscribers. Each channel can have zero or more subscribers. A channel subscriber will receive all commands sent to the channel as long as the subscriber is active. In general, a channel subscriber represents a unique device. A device can be a subscriber of multiple channels.

Creating a channel

When you create a channel you should provide a descriptive channel name and description. This is to provide some human readable information that can be shared with potential subscribers and help you differentiate the channels you create.

When you create a channel, a pair of authentication keys are also created:

• channel_key: Can be used to access the Channel “Editor” endpoints. These endpoints can be used to control the channel’s life-cycle, retrieve and update channel information and list subscribers. Only share the channel_key with people that should be able to have “Editor” access to your channel.
• subscriber_key: Can be used to access the channel subscriber creation endpoint. A channel creator can use this key to add subscribers to the channel, or share the key with potential subscribers so they can add them self to the channel.

Channel options

When creating a channel certain features of the channel can be controlled through the channel settings.

• offset: Used as the default delay when forwarding messages to subscribers with no subscriber specific delay set. Defaults to 0.
• device_events: If enabled, the Handy API v3 SSE endpoint can be used to receive device events from all active channel subscribers. Defaults to false.
• device_info: The device information used as a mock device representing the channel. Used when accessing information endpoints (example GET /info). Default values used if not provided.

Sending data to a channel

The Channel API itself does not have an endpoint for sending data to a channel. Instead, data is sent to a channel and forwarded to the subscribers by using a channel reference in place of the device connection key in supported Handy API v3 endpoints.

To make an endpoint identify a channel as a recipient, the channel reference needs to be prefixed with the string chref:

Example: To send some command to the channel with the channel reference:RDNMPPGNFCCTP1TP3S34FJPM78 use the value chref:RDNMPPGNFCCTP1TP3S34FJPM78 in place of the device connection key.