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

</aside>

The Channel API offers utilities to simplify sending commands to multiple devices at the same time, i.e. multi-casting.

Channels

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

TODO: Image of 1—to-N command

Creating a channel

Anyone can create a channel. No preregistration or user account is required. 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, get channel information, update channel properties and list subscribers. The channel-key is also used to reference the channel in multicast supporting API endpoints. Only share the channel-key with people that should be able to send data to your channel and have “Editor” access.
• subscriber-key: Can be used to access the channel subscriber signup 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 your channel.

Closing a channel

When you are done using the channel you should close the channel. A closed channel can not receive any more data, and new subscribers can not be added to it. Closing a channel also closes all remaining active subscribers.

<aside> 💡 Channels with no activity will be closed automatically after X hours.

</aside>

Subscribers

Adding subscribers

In order to add a device as a channel subscriber you need to know the connection key of the device and the channel subscriber-key.

This provides you with two different ways to add subscribers to a channel:

1. Collect connection-keys and add them to your channel.
2. Distribute the subscriber-key to potential channel subscribers in order for them to add them self to you channel.