Channels

Search…
Channels
Our channels enable developers to implement different types of chat messaging capabilities into their applications easily
Users can create and join channels where they will be able to participate and chat with other users. A channel can support up to 300,000 members and can contain an unlimited number of messages. Any message exchanged in the channels will be pushed to all other members of the channel in real-time.
Channel Model
When you are observing channels, it will always appear in this format.
1
{
2
      "channelId": "string",
3
      "isDistinct": true,
4
      "metadata": {},
5
      "type": "standard",
6
      "tags": [
7
        "string"
8
      ],
9
      "isMuted": true,
10
      "isRateLimited": true,
11
      "muteTimeout": "2021-08-26T06:05:25.996Z",
12
      "rateLimit": 0,
13
      "rateLimitWindow": 0,
14
      "rateLimitTimeout": "2021-08-26T06:05:25.996Z",
15
      "displayName": "string",
16
      "messageAutoDeleteEnabled": true,
17
      "autoDeleteMessageByFlagLimit": 0,
18
      "memberCount": 0,
19
      "messageCount": 0,
20
      "lastActivity": "2021-08-26T06:05:25.996Z",
21
      "createdAt": "2021-08-26T06:05:25.996Z",
22
      "updatedAt": "2021-08-26T06:05:25.996Z",
23
      "avatar": {}
24
    }
Copied!
Channel Description
Name
Data Type
Description
Attributes
channelId
String
ID of the channel
​
isDistinct
Boolean
Is channel distinct?
​
metadata
Object
Additional properties to support custom fields
​
type
String
Type of channel
Enum:[standard, private, conversation, broadcast, community, live]
tags
Array.<String>
Tags used for searching
​
isMuted
Boolean
Is this channel muted?
Computed by using muteTimeout
isRateLimited
Boolean
This channel has limited sending rate?
Computed by using muteTimeout
muteTimeout
string($date-time)
Date/time to disable mute
​
rateLimit
Integer
Number of messages within rate limit
​
rateLimitWindow
Integer
Waiting time interval before reseting rateLimit to 0
​
rateLimitTimeout
string($date-time)
Date/time to suppress limitation of sending rate
​
displayName
String
Channel name for displaying
​
messageAutoDeleteEnabled
Boolean
Will message in this channel be deleted when the user will flag until flag limit?
​
autoDeleteMessageByFlagLimit
Number
Number of flags that will force a message to be deleted automatically
​
memberCount
Integer
Number of members in channel
​
messageCount
Integer
Number of messages in channel
​
lastActivity
string($date-time)
Date/time of user's last activity related to the channel (E.g. add/remove member)
​
createdAt
string($date-time)
Date/time the channel was created
​
updatedAt
string($date-time)
Date/time the channel was last updated
​
avatar
Object
Data of the avatar
​
Channel Types
Amity's Chat SDK supports the creations of 4 types of chat channels. Each type is designed to match a particular use-case for chat channels. Here's a table showing what features each channel offers:
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
Community
All community channels are visible on the Amity Social Cloud Console.
The community channel is our default channel type and can be discovered by all users and admins. It acts as a public chat channel that showcases all of the features that our SDK's have to offer.
Typical use cases:
Team collaboration
Online gaming
Celebrity fan club
Live streaming
Any type of public chat
Live
All live channels are visible on the Amity Social Cloud Console.
Live channels offer the ability for users and admins to create channels with exclusive memberships. The live channel is identical to our Community channel in features with the caveat that users will not be able to discover the channel when querying for all channels unless they are already a member of it. However, users and admins can still invite other users to join the channel.
Typical use cases:
Healthcare
Project Discussion
Any type of private chat
Community and Live channel types can use our SDK moderation tools:
Message and user flagging
Muting/Unmuting users
Banning/Unbanning users from channel
Profanity filters
Whitelisted URLs
User rate-limiting
Broadcast
All broadcast channels are visible on the Amity Social Cloud Console.
The Broadcast channel is heavily adopted by corporate users who constantly promote or advertise their products, or make the announcement to drive awareness. Unlike other channel types, broadcast channels only allow admin users to send messages from Console, and everyone else in the channel will be under read-only mode.
Since this is a one-way communication channel, tailored moderation tools are provided as well, for instance, users won't be able to flag message / user in the channel.
Typical use cases:
Marketing & Advertising
School / Government Announcements
Conversation
Conversation channels are NOT visible on the Amity Social Cloud Console.
The Conversation channel is our solution to 1-on-1 messaging. Unlike the other channel types, a Conversation channel can be created simply by knowing the userId of the user we want to converse with. Users can start conversations with any other user and only they will be able to see their conversation.
There are no moderation tools for Conversation channels, users will be able to converse freely with no oversight!
Typical use cases:
Hospitality
Financial Consultancy
Customer Support
Since this is similar to 1-on-1 messaging, Conversation channels have some limitations. The following are not allowed:
Join and leave channel
Ban and unban channel members
Add and remove channel members
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, getChannels: method supports all channel types including Broadcast, Private and Standard.
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
SDK 	Supported
Community
All users and admins
Users and admins
All Moderation tools
Yes
Live
Only members and admins
Users and admins
All Moderation tools
Yes
Broadcast
All users and admins
Admins
Admin Moderation tools
No
Conversation
Only members
Users
No Moderation tools
Yes
Each channel is identified by a 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 to automatically generate one for you.
There are 4 channel types 1. Community: a channel that is discoverable by all users. 2. Live: a channel that is discoverable only if user is already added as a member. 3. Broadcast: a channel that limits message creation to only Admin user. Message can only be created from Console. 4. Conversation: a one-to-one chat that once created will not be available on Admin panel.
There are three ways of obtaining an AmityChannel object: via create, join, or get methods. AmityChannel management methods are all contained in the AmityChannelRepository class. To get an instance of AmityChannelRepository:
1
val channelRepository = AmityChatClient.newChannelRepository()
Copied!
​
Create Community Channel
The SDK provides 2 typical ways of channel creation.
1.
Channel creation with specific channelId.
2.
Channel creation with auto-generation of channelId.
The channel creation API guarantees that the requested channel is a new channel. If the channel already exists, the error will be an AmityExceptionwith code 400900
The createChannel() method initiates channel creation method chain and let you choose which channel type to be created.
To let SDK handle channelId generation, uses withDisplayName() method to skip channelId specification.
1
// create channel by specifying channelId
2
channelRepository.createChannel()
3
                .communityType()
4
                .withChannelId("Weekly-promo")
5
                .displayName("Weekly promo") // optional
6
                .metadata(jsonObject) // optional
7
                .tags(AmityTags(listOf("Promotion", "New Arrival"))) // optional
8
                .build()
9
                .create()
10
                .subscribe()
11
​
12
// let SDK handle channelId generation                               
13
channelRepository.createChannel()
14
                .communityType()
15
                .withDisplayName("Weekly promo")
16
                .metadata(jsonObject) // optional
17
                .tags(AmityTags(listOf("Promotion", "New Arrival"))) // optional
18
                .build()
19
                .create()
20
                .subscribe()
Copied!
Create Live Channel
The SDK provides 2 typical ways of channel creation.
1.
Channel creation with specific channelId.
2.
Channel creation with auto-generation of channelId.
The channel creation API guarantees that the requested channel is a new channel. If the channel already exists, the error will be an AmityExceptionwith code 400900
The createChannel() method initiates channel creation method chain and let you choose which channel type to be created.
To let SDK handle channelId generation, uses withDisplayName() method to skip channelId specification.
1
// create channel by specifying channelId
2
channelRepository.createChannel()
3
                .liveType()
4
                .withChannelId("Weekly-promo")
5
                .displayName("Weekly promo") // optional
6
                .metadata(jsonObject) // optional
7
                .tags(AmityTags(listOf("Promotion", "New Arrival"))) // optional
8
                .build()
9
                .create()
10
                .subscribe()
11
​
12
// let SDK handle channelId generation                               
13
channelRepository.createChannel()
14
                .liveType()
15
                .withDisplayName("Weekly promo")
16
                .metadata(jsonObject) // optional
17
                .tags(AmityTags(listOf("Promotion", "New Arrival"))) // optional
18
                .build()
19
                .create()
20
                .subscribe()
Copied!
Create Conversation
Channel of type Conversation can also be created with createChannel() method chain. However, the channelId is always being generated by SDK.
To create a conversation channel with a user, pass the user's userId to withUserId() method.
1
// let SDK handle channelId generation                               
2
channelRepository.createChannel()
3
                .conversationType()
4
                .withUserId(userId)
5
                .displayName("BFF") // optional
6
                .metadata(jsonObject) // optional
7
                .tags(AmityTags(listOf("friends")) // optional
8
                .build()
9
                .create()
10
                .subscribe()
Copied!
Conversation channel is unique based on its membership. When creating conversation, the system will check if a channel with the same membership already exists. If such channel already exists, the system will return the existing channel instead of creating a new one.
Join Channel
The joinChannel() method will add the active user as a member of the channel.
This API can be called as many times as needed. If the channel has already been joined, a "success" result will be returned, ie., going into doOnSuccess{}block.
1
channelRepository.joinChannel(channelId)
2
                .subscribe()
Copied!
Get Channel
In the case where you only want to fetch a channel's data without joining, you can use the getChannel() method:
1
channelRepository.getChanel(channelId)
2
                .subscribe( { amityChannel -> ... } )
Copied!
Channel Query
The AmityChannelRepository provides the getChannels() method which initiates channel query method chain. The query returns Flowable<PagedList<AmityChannel>> representing all matching channels available.
1
// Query for Community type
2
channelRepository.getChannels()
3
                .communityType()
4
                .build()
5
                .query()        
6
                .subscribe( { adapter.submitList(it)} )
7
​
8
// Query for Live type
9
channelRepository.getChannels()
10
                .liveType()
11
                .build()
12
                .query()        
13
                .subscribe( { adapter.submitList(it)} )
14
​
15
// Query for Broadcast type
16
channelRepository.getChannels()
17
                .broadcastType()
18
                .build()
19
                .query()        
20
                .subscribe( { adapter.submitList(it)} )
21
​
22
// Query for Conversation type
23
channelRepository.getChannels()
24
                .conversationType()
25
                .build()
26
                .query()        
27
                .subscribe( { adapter.submitList(it)} )     
28
​
29
// Query for Multiple types
30
val types : List<AmityChannel.Type> = // create a list of your desired types
31
​
32
channelRepository.getChannels()
33
                .types(types)
34
                .build()
35
                .query()        
36
                .subscribe( { adapter.submitList(it)} )
Copied!
Channel Filtering
the filter() method lets you filter channels based on the current user membership status
the includingTags() and excludingTags() methods let you filter channels based on the tags set (or not set) in each channel
1
val includingTags = AmityTags()
2
includingTags.add("games")
3
​
4
// Query for Community channels where the user is member, tagged as "games"
5
channelRepository.getChannels()
6
                .communityType()
7
                .filter(AmityChannelFilter.MEMBER)
8
                .includingTags(includingTags)
9
                .build()
10
                .query()
11
                .subscribe( { adapter.submitList(it)} )
Copied!
1
val includingTags = AmityTags()
2
includingTags.add("games");
3
​
4
val excludingTags = AmityTags()
5
excludingTags.add("staff-only")
6
​
7
// Query for Community channels where the user is not member, tagged as "games", and not tagged as "staff-only"
8
channelRepository.getChannels()
9
                .communityType()
10
                .filter(AmityChannelFilter.NOT_MEMBER)
11
                .includingTags(includingTags)
12
                .excludingTags(excludingTags)
13
                .build()
14
                .query()
15
                .subscribe( { adapter.submitList(it)} )
Copied!
Metadata
Metadata is a general purpose data store that is automatically synchronized to all users of a channel. It is designed to store contextual information about a specific channel. The metadata is a JSON object which can store 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 on the entire store. This means that multiple mutations by independent users to the metadata object will result in a single stored value. The metadata object set by last user overrides any previous values. No locking, merging, or other coordination is performed across participants.
To set metadata, simply call the following method:
1
val metadata = channel.getMetadata()
2
metadata.addProperty("tutorial_url", "https://docs.amity.technology/")
3
​
4
channelRepository.getChannels()
5
                .updateChannel(channelId)
6
                .metadata(metadata)
7
                .build()
8
                .update()
9
                .subscribe()
Copied!
Participation
All participation-related methods in a channel fall under a separate AmityChannelParticipation model. You can access AmityChannelParticipation from AmityChannelRepository.membership() method as well as from AmityChannel.membership() method.
1
// Access from AmityChannelRepository
2
val membership = channelRepository.membership(channelId)
3
​
4
// AmityChannel object already knows its channelId
5
val membership = channel.membership();
Copied!
Member Listing
The getMembers() provides a list of members in the given channel
1
membership.getMembers()
2
                .build()
3
                .query()
4
                .subscribe( { adapter.submitList()} )
Copied!
Member Search
The searchMembers() provides an ability to search for members in the given channel by displayname, roles, and membership status
1
membership.searchMembers("alex")
2
                .roles(listOf("moderator"))
3
                .membershipFilter(AmityChannelMembership.MEMBER)
4
                .build()
5
                .query()
6
                .getPagingData( { adapter.submitData()} )
Copied!
Manage Members
You can add and remove members, as well as removing yourself as a member of a channel (leaving the channel) via AmityChannelParticipation model should you have appropriate privileges.
1
// Add 'user1' and 'user2' to this channel
2
membership.addMembers(listOf("user1", "user2")).subscribe()
3
​
4
// Remove 'user3' from this channel
5
membership.removeMembers(listOf("user3")).subscribe()
Copied!
Role and Permission
Creator of the channel can add and remove the role of user via AmityChannelModeration.
Role
1
//Add role
2
AmityChatClient.newChannelRepository()
3
                .moderation("channelId")
4
                .addRole("admin", listOf("userId1, userId2"))
5
                .subscribe()  
6
​
7
//Remove role
8
AmityChatClient.newChannelRepository()
9
                .moderation("channelId")
10
                .removeRole("admin", listOf("userId1, userId2"))
11
                .subscribe()  
Copied!
Query memberships by role
The AmityChannelParticipation provides a list of members by role in the given channel.
1
AmityChatClient.newChannelRepository()
2
                .membership("channelId")
3
                .getMembers()
4
                .roles(listOf("roleName"))
5
                .build()
6
                .query()
7
                .subscribe()
Copied!
Permission
You can check your permission in channel by sending AmityPermission enums to AmityCoreClient.hasPermission(amityPermission).
1
 AmityCoreClient.hasPermission(amityPermission)
2
                .atChannel("channelId")
3
                .check()
4
                .subscribe()
Copied!
Reading Status And Unread Count
The AmityChannelRepository provides getTotalUnreadCount() method. It's giving the flowable of the number of messages that the current user has yet to read. This count is the sum of all the unreadCount channels properties where the user is a member of. 
1
// unread count of all channels
2
channelRepository.getTotalUnreadCount()
3
                .doOnNext( totalUnreadCount -> {
4
​
5
                })
6
                .subscribe();
7
​
8
// channel unread count
9
val unreadCount = channel.getUnreadCount()
10
​
11
​
12
// has unread mention
13
val hasUnreadMention = channel.hasUnreadMention()
Copied!
Unread mention
To check whether the current user has been mentioned on one of the unread messages
1
// has unread mention
2
val hasUnreadMention = channel.hasUnreadMention()
Copied!
Reading status update
To let the server know when the current user is reading one channel, hence resetting that channel unreadCount to zero, the participation membership exposes the AmityChannelParticipation.startReading() and AmityChannelParticipation.stopReading() methods.
You can call both methods as much as you want, the SDK takes care of multi-device management: therefore a user can read multiple channels, from one or multiple devices at once. In case of an abrupt disconnection (whether because the app was killed, or the internet went down, etc.) the SDK backend will automatically call the AmityChannelParticipation.stopReading() on the user behalf.
1
// Start reading a channel
2
membership.startReading()
3
​
4
// Stop reading a channel
5
membership.stopReading()
Copied!
Data-Stream
User
Last modified 25d ago