> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hop.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Overview

> Channels allows you to easily create direct or grouped realtime message channels between users, server-side applications, IoT devices and more. You can use them to publish realtime events & even store realtime state objects which you can handle using our client-side SDKs.

Channels are feature-rich and can be of multiple different visibility types and
have multiple Capabilities enabled, allowing you to create anything from a
realtime stock ticker to a fully feature-rich group messaging app.

Some nicities provided by Channels include:

* Channels can be of the `unprotected` type, which means that you don't need to
  worry about handing out tokens to users on your frontend. This is useful if
  you want to display realtime data on a frontend application that doesn't
  require user sign-in, for example.
* You can send events directly to [Tokens](./tokens), instead of sending
  them to channels
* You can keep realtime, persisted "state" within a channel, which all clients
  are kept in sync with when connecting & when it's updated.
  [Read more ➜](./channel-state)
* All capabilities can be mixed and matched with each other, allowing you to
  reap powerful benefits from individual channels without having to create hacky
  workarounds

For most use cases, you'll need a protected server-side application (e.g. an
API) which can use the [Hop SDK](/sdks/server/js) to
[generate Tokens](./tokens) and
[create Channels](./creating-channels). You can then use the
[client-side SDKs](/sdks/client/js) to subscribe to channels.

## Jump To

* [Learn about Channel State](./channel-state)
* [Learn about Channel Tokens (authenticate users to Channels)](./tokens)
* [Using Channels with React](./reference/react)
* [Creating Channels with the Hop SDK](./reference/creating-channels)
* [Updating Channel State using the Hop SDK](./reference/updating-channel-state)
* [Sending Messages to Channels using the Hop SDK](./reference/sending-messages)

## Concepts

### Clients

The client (or "user") is the entity that subscribes to Channels, using either
the Hop SDK or via a custom [Leap](./internals/leap) implementation. The
client can be anything: a React app, a server-side application or an IoT device,
for example.

### Tokens

For a client application to authenticate with protected (public & private)
Channels, they will need to use token authentication. Tokens (`leap_token_xxx`)
can be generated using the Hop API or SDK from your backend. Tokens can contain
metadata - for example, you could include the user ID this token is generated
for in. You are expected to securely hand this token to a client application,
which they can then use to authenticate with Channels through the Hop client
SDK.

Tokens can subscribe to many channels at once. They are permanent until deleted.

If you have a database of users, then you should create a token for each
individual user that needs to connect to Channels and store it in relation to
their user, then re-use that same token when they need to connect again in the
future.

You can connect and authenticate with Channels multiple times under the same
token.

### Sessions

When a client SDK connects to the Channels socket, they are attached to a
session individual to that token. Then, if a user connects multiple times under
one token, they are connected to the same session. As a developer, you shouldn't
need to worry about this resource - just know that it's used to keep a
consistent and uninterrupted socket connection during unstable network
conditions. Sessions automatically die once there have been no connected clients
for a 30 second period. You can read more about them in the
[Leap](./internals/leap) documentation.

#### Connections

Individual connections to the Channels socket are a separate resource, and while
they're attached to sessions, they get their own identifier which you can use to
send messages to a single connection or "device".

### Channel Subscriptions

A channel subscription refers to a client token being subscribed to a channel.

**Important**: If you are just subscribing to unprotected channels on your
frontend, then all channel subscriptions are ephemeral and only last the
duration of the session / socket connection.

There are 3 ways a token can be subscribed to a channel:

* When creating the token, you can specify a list of "default channels" the
  token should be subcribed to
* Through the local client SDKs, the client can call the `subscribe` method with
  a channel ID. If the channel is private, then a webhook call will be required
  to succeed before the client is subscribed.
* Through the server-side SDKs, you can call a method to subscribe one or
  multiple tokens to a channel

When client subscriptions are created, the realtime clients will instantly start
receiving events from these channels.

All channel subscriptions are permanent across all sessions, and will last until
a token is unsubscribed from a channel through the server-side API or local SDK.
However, you can mark a subscription as `ephemeral`, which will delete the
subscription when the session dies.

```
                                  ┌──────► channel_0
                                  │
                                  ├──────► channel_1
                                  │
User (Leap Token) ◄───► Session ◄─┼──────► channel_2
                                  │
                                  ├──────► channel_3
                                  │
                                  └──────► channel_4
```

### Channels

By default, channels are direct, private, server->client realtime messaging
rooms, however, channels are feature-rich and have be of multiple visibility
types, and have multiple different Capabilities assigned to them. By default,
channels are permanent until you delete them, however for some use cases, it
might make more sense to give them the `ephemeral` capability, which makes them
automatically delete once all subscribers have disconnected.

#### Visibility Types

Channels can have one of 3 visibility types:

* Private
* Public
* Unprotected

**Private** channels allow you to individually grant tokens access to channels,
either by calling a method from the server-side SDK or by responding to a
webhook call when tokens try to subscribe, which you can set up on the Channels
console page

**Public** channels allow anyone to join them, given they're authenticated under
your project and know the channel ID.

**Unprotected** channels allow anyone to join them, even if they're not
authenticated with a token, given they know the channel ID

#### State

State acts as a realtime data store attached to each channel. See
[Channel State](./channel-state)

### Messages

You can use the Hop API or SDK to easily send messages of any size to channels,
which can then be handled by channel subscribers.

[How to send Messages to Channels](./reference/sending-messages)