Channels

Channels are a type of conversation that provides the following trade-offs:

  • Allows up to 250 participants instead of only the 25 allowed by conversations
  • Does not provide any read or delivery receipts
  • Has a Unique Name
  • Maintain a single shared view for all users
    • This means Block Lists do not apply to Channels
    • This means that the only type of deletion allowed within a Channel is deletion that affects All users

There are a few key differences between the Conversation API and Channel API:

  • lastMessage: Conversations track the last message in your conversation so that you can render a Conversation List showing the last message text for each conversation. Channels do not currently support this.
  • unreadCount: Conversations track the number of messages your user has left unread; Channels do not currently support this.
  • participants: Conversations manage an array of participants, up to 25 of them. Channels, which can contain up to 250 participants requires a separate API to load these users, and the term “Member” or “Membership” is used to describe them rather than participants.

Creating a channel

Channel objects are created by calling client.createChannel(), passing in a hash with array of User IDs to be included in the conversation:

var channel = client.createChannel({
  membership: ['layer:///identities/UserA', 'layer:///identities/UserB'],
  name: 'layer-sample-channel'
}).send();

Note

Typically you should send a channel to the server via channel.send() as soon as you create them. However, if you have not yet called channel.send() prior to sending your first message on that channel, the channel will be sent for you.

Note

You don’t have to include the current user in the set of members. The current user is automatically added to all conversations they create.

Channel Names

Channel names are required, and must be unique. If a channel with the specified name exists, there are two possible outcomes:

  1. You are already a member of the matching channel, and its properties will be copied into the Channel object you created. Note that this could potentially trigger an id change in your Channel object.
  2. A conflict-error will be returned if there is a matching channel and you are NOT a member of it; this event should be watched for so that your user can be prompted for a new name.
var channel = client.createChannel({
  membership: ['layer:///identities/UserA', 'layer:///identities/UserB'],
  name: 'layer-sample-channel'
}).send();

channel.on('channels:sent-error', function() {
  channel.name = 'layer-sample-channel-2';
  channel.send();
});

Note

The concept of a public channel will be introduced later; currently all channels are private, and only visible to members of the channel.

Membership

Members of a Channel are not a property of the channel the way that participants are a property of layer.Conversation; rather it’s a resource that must be Queried and loaded from the server:

var membershipQuery = client.createQuery({
  model: layer.Query.Membership,
  predicate: "channel.id = 'layer:///channels/UUID'"
});
membershipQuery.on('change', function(evt) {
  var members = query.data;
  myMemberListRenderer(members);
});

While conversation participants is limited to just 25, a channel may have up to 250 members, and this number may increase in the future. This requires a pageable list of members rather than a directly accessible list within the Channel object.

Adding/Removing Members

Adding and removing members (including yourself) is not currently supported for Clients; see the Server API instead.

Conversations Messages