Channel Management

Channel Members

When a user joins a channel, they are able to observe and chat with other users in that channel. They are also automatically considered a member of that channel. The Chat SDK provides the ability to view which users are currently in the channel as well as invite other users to join the channel.

Channel Type	Discoverable by	Message sending privileges	Moderation access
Community	All users and admins	Users and admins	All Moderation tools
Live	Only members and admins	Users and admins	All Moderation tools
Broadcast	All users and admins	Admins	Admin Moderation tools
Conversation	Only members	Users	No Moderation tools

Each channel is identified by an unique channelId, which is any string that uniquely identifies the channel and is immutable through its lifetime. When creating channels, you can specify your own channelId, or leave it to Amity's Chat SDK to automatically generate one for you.

There can be only one and one only channel with a given channelId an error will be thrown when trying to generate two channels with the same channelId.

There are three ways of obtaining a channel: via create, join, or get. They all return a LiveObject with the complete channel model. However, createChannel guarantees that the requested channel is a new channel, whereas joinChannel will attempt to join an existing channel. If there is a requirement to create a new channel, then use of createChannel then call joinChannel. Lastly calling getChannel only gives you back the channel LiveObject, but it won't make the current user join said channel.

Create Channel

ChannelRepository provides createChannel method to create a new channel. It supports creating of 3 types of channels Community, Live and Conversation. Each channel type has specific builder classes which helps you to create that particular channel. Build your channel information first and then create the particular channel.

import { ChannelRepository, ChannelType } from '@amityco/js-sdk';

const liveChannel = ChannelRepository.createChannel({
  channelId: 'channel1',
  type: ChannelType.Community,
  userIds: [ 'user1', 'user2' ],
})

liveChannel.once('dataUpdated', model => {
  console.log(`Channel created: ${model.channelId}`);
});

liveChannel.once('dataError', error => {
  // Handle channel create error (non-unique channelID)
});

The above code creates a channel and notifies you through observer block.

In the case that there is already an existing channel with the same channelId, the LiveObject will notify you with an error object.

The channelId parameter in createChannel can be undefined when this happens, the SDK will generate an unique channelId for this channel, ensuring no unique ID conflicts.

3 channel types can be created through SDK i.e Community, Live and Conversation. Creation of Private and Standard type has been removed. Creation of Broadcast channel type is not supported through the SDK. But for query queryChannels method supports all channel types including Broadcast, Private and Standard.

Create Conversation:

The Chat SDK provides a convenient method which creates a conversation channel type.

import { ChannelRepository, ChannelType } from "@amityco/js-sdk"

const liveChannel = ChannelRepository.createChannel({ type: ChannelType.Conversation })

liveChannel.once('dataUpdated', () => {
  console.log('channel created');
});

Conversation channel is unique based on its membership. When creating conversation the system will check if channel with the same membership already exists, if such channel already exists the system will return existing channel instead of creating a new one.

Get Channel

const liveChannel = ChannelRepository.getChannel('channel3');

liveChannel.once('dataUpdated', data => {
  ...
});

Join Channel

const isJoined = await ChannelRepository.joinChannel({
  channelId: 'channel2'
});

Channel Query

ChannelRepository provides a way to query list of channels using queryChannels method. It returns aLiveCollection of all the matching channels available. This live collection returned will automatically update and notify you on any channel modifications.

import { 
  ChannelRepository, 
  ChannelType, 
  ChannelFilter, 
  ChannelSortingMethod,
} from '@amityco/js-sdk';

let channels;

const liveCollection = ChannelRepository.queryChannels({
  keyword: 'asd',
  types: [ChannelType.Conversation],
  filter: ChannelFilter.Member,
  isDeleted: false,
  tags: ['tag1'],
  excludeTags: ['tag2'],
  sortBy: ChannelSortingMethod.LastCreated
});

liveCollection.on('dataUpdated', models => {
  channels = models;
});

channels = liveCollection.models;

Channel Filtering

You can filter channels by various criteria such as tags, excludingTags, isDeleted channels etc.

Set Channel Properties

All channels have the following properties:

• Channel display name

• Channel Avatar

• Tags

• Metada

You can set each property using their respective setter methods.

Set Display Name

Every channel contains an optional displayName property. This property is mainly used to identify the channel in push notifications, but it is also exposed to the application via Channel object.

You can set a channel's displayName with the following method:

await channelRepo.ChannelRepository({
  channelId: 'channel1',
  displayName: 'Channel Eko',
});

An optional completion callback is available to inform you on whether the request has succeeded or not.

Set Avatar

There is no specific method for setting a channel's avatarFileId but you can use the updateChannel method for this task. Refer to Update Channel section.

You need to upload the avatar first and retrieve the avatar file ID which you need to pass as a parameter when updating the channel. You can refer to Files page to create and get the file information.

Set Tags

Tags are usually one to three words that provide details about a channel as well as post, comment, community, and message. They are simple descriptions and are mostly used in querying related items that have the same tags.

Tags are optional. Up to five tags can be added and each tag can be up to 24 characters long.

You can set a channel's tags with the following method:

channelRepo.setTags({
  channelId: 'channel1',
  tags: ['travel', 'Hong Kong Disneyland']
})
  .then(() => {
    // success
  }).catch(error => {
    // handle error
  });

Set Metadata

Metadata is a general purpose data store that is automatically synchronized to all the channel members. It is meant as an elegant mechanism to store contextual information about a specific channel. The data can be any number of JSON key value pairs up to 100 kb. Example use cases include:

• Conversation title or cover photo

• Global conversation settings

Metadata is implemented with last writer wins semantics: multiple mutations by independent users to the metadata object will result in a single stored value. No locking, merging, or other coordination is performed across multiple writes on the data.

await ChannelRepository.setMetadata({
  channelId: 'channel1',
  metadata: { hello: 'world' },
});

The completion block will be triggered with the outcome of the request. The latest metadata of the channel is always exposed as part of the metadata property on the channel model.

Update Channel

You can update the following channel properties using the updateChannel method:

• Channel display name

• Channel Avatar

• Tags

• Metada

To set metadata, call the setMetadataForChannel: method:

Refer to this table for the parameters you can pass to the updateChannel method.

channelRepo.setMetadata({
  channelId: 'channel1',
  metadata: { hello: 'world' },
})
  .then(() => {
    // success
  }).catch(error => {
    console.log('Metadata set fail');
  });

Parameter	Data type	Description
displayName	String	Channel display name
avatarFileId	String	Avatar file ID
tags	Array.<String>	Tags used in querying
metadata	Object	Metadata of channel

The completion block will be triggered with the outcome of the request. The latest metadata of the channel is always exposed as part of the metadata property on the channel model.

To update any of the channel properties, simply pass the channel ID along with the channel properties that you want to update and the new property values.

import { ChannelRepository } from '@amityco/js-sdk';

// Update channel display name and avatar
await ChannelRepository.updateChannel({ 
    channelId: 'channelId', 
    displayName: channelName,
    avatarFileId: fileId,
 })

When updating the channel avatar, you need to upload the avatar first and retrieve the avatar file ID. You can refer to Files page to create and get the file information.

The updateChannel method will throw an error if an incorrect parameter is passed.

When updating the channel avatar, you need to upload the avatar first and retrieve the avatar file ID. You can refer to Files page to create and get the file information.

Leave Channel

The leaveChannel method will remove the active user as a member of the channel. If a user leaves a channel, the user can't receive messages from the channel anymore.

Required parameter

• channelId (string) - the ID of the channel to leave

import { ChannelMembershipRepository } from '@amityco/js-sdk';

await ChannelMembershipRepository.leaveChannel({ 
  channelId: 'channelId', 
})

Delete Channel

Deleting a channel is not supported in SDK. Refer to this section for the instructions on how to delete a channel via API.