<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.

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.

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:yx0dEvnDXRGEIIUC use the value chref:yx0dEvnDXRGEIIUC in place of the device connection key.

Anyone who knows the channel reference can send data to the channel, so only share the channel reference with those who should be able to do so.

Channel responses

When sending a command to a channel using one of the multicast supported REST API endpoints, the received response will always be in the same format as the specific API endpoint.

As a consequence, you will always receive a single response, even though your channel may have zero or more subscribers.

Unlike when sending a command to a single device referencing a connection-key, the service will not wait for an actual response from any of the subscribers before returning a response. Instead a response is returned immediately and will always return a response indicating success, as long as the data could be forwarded to the channel.