Channel members

Add channel members

Members can be added to a channel either when creating it or by using the addMembers method.

When creating a channel

// members can be added by passing an array of user IDs
const channel = client.channel("messaging", randomID, {
  members: ["userid1", "userid2", "userid3"],
});

// or by passing objects
const channel = client.channel("messaging", randomID, {
  members: [
    { user_id: "userid1" },
    { user_id: "userid2" },
    { user_id: "userid3" },
  ],
});

let channelController = try ChatClient.shared.channelController(
	createChannelWithId: randomId,
	members: [
		"userid1",
		"userid2",
		"userid3"
	]
)
// Calling synchronize() is required to persist the channel to the server.
channelController.synchronize()

ChannelGetResponse channel = Channel.getOrCreate("messaging", "channel-1")
    .data(
        ChannelRequestObject.builder()
            .createdBy(user1)
            .members(
                users.stream().map((x) -> ChannelMemberRequestObject.builder().user(x).build())
                    .collect(Collectors.toList()))
            .build())
    .request();

Using `addMembers` method

await channel.addMembers(["userid1", "userid2"]);

// you can set channel_role in the meantime
await channel.addMembers([
  { user_id: "userid1", channel_role: "channel_moderator" },
]);

// members can be added by passing an array of user IDs
let channelController = ChatClient.shared.channelController(for: randomId)
channelController.addMembers(userIds: ["userid1", "userid2", "userid3"])

// or by passing objects
let channelController = ChatClient.shared.channelController(for: randomId)
channelController.addMembers([
	MemberInfo(userId: "userid1"),
	MemberInfo(userId: "userid2"),
	MemberInfo(userId: "userid3", extraData: ["custom": .string("value")])
])

Channel.update("messaging", "channel-1").addMember("user-3").request();

Note: You can only add up to 100 members at once.

Message parameter

You can optionally include a message object to allow client-side SDKs to generate a system message. This feature is available for both adding and removing members.

await channel.addMembers(["userid1"], { text: "Tommaso joined the channel." });

// using server-side client, you need to specify the sender user_id
await channel.addMembers(["userid1"], {
  text: "Tommaso joined the channel.",
  user_id: "userid2",
});

channelController.addMembers(
	userIds: ['userid1'],
	message: "Tommaso joined the channel."
) { error in
	// handle error
}

Channel.update("messaging", "channel-1").addMember("user-3")
    .message(MessageRequestObject.builder().text("User 3 joined!").build()).request();

Hide history

When members join a channel, you can specify whether they have access to the channel’s history.

By default, new members can see the history. To hide it, set the hide_history parameter to true.

await channel.addMembers(["userid1"], undefined, { hide_history: true });

channelController.addMembers(userIds: ['userid1'], hideHistory: true)

Channel.update("messaging", "channel-1").addMember("user-3").hideHistory(true).request();

Channel member custom data

Custom data can be added at the channel member level. Ensure it does not exceed 5KB.

// add custom data while creating the channel
const channel = client.channel("messaging", randomID, {
  members: [
    { user_id: "userid1", key1: "value1" },
    { user_id: "userid2", key1: "value1" },
    { user_id: "userid3", key2: "value2" },
  ],
});

// add custom data with `addMembers` method
await channel.addMembers([{ user_id: "userid1", key1: "value1" }]);

channelController.addMembers([
	MemberInfo(userId: "userid1", extraData: ["key1": .string("value1")]),
	MemberInfo(userId: "userid2", extraData: ["key2": .string("value2")]),
	MemberInfo(userId: "userid3", extraData: ["key3": .string("value3")])
])

Remove channel members / Leave a channel

Remove channel members

removeMembers method allows you to remove members from a channel.

await channel.removeMembers(["userid1", "userid2"]);

channelController.removeMembers(userIds: ["userid1", "userid2"])

Note: You can only remove up to 100 members at once.

Leave a channel

Users can leave a channel without moderator-level permissions.

Ensure channel members have the Leave Own Channel permission enabled.

// remove own channel membership
await channel.removeMembers(["myuserid"]);

channelController.removeMembers(userIds: ["myuserid"])

You can familiarize yourself with all permissions in Permissions section

Add / Remove moderators to a channel

Using the addModerators method adds the given users as moderators (or updates their role to moderator if already members), while demoteModerators removes the moderator status.

Add moderators

The addModerators method adds specified users as moderators to a channel. If the users are already members, their role is upgraded to moderator.

await channel.addModerators(["userid1", "userid2"]);

Remove moderators

The demoteModerators method removes the moderator role from specified users.

await channel.demoteModerators(["userid1"]);

These operations can only be performed server-side, and a maximum of 100 moderators can be added or removed at once.

Update channel members

Channel members can be partially updated. Only custom data and channel roles are eligible for modification.

You can set or unset fields, either separately or in the same call.

// set some fields
await channel.partialUpdateMember(user_id, {
  set: {
    key1: "new value 1",
    key2: "new value 2",
    channel_role: "channel_moderator",
  },
});

// unset some fields
await channel.partialUpdateMember(user_id, {
  unset: ["key1", "key2"],
});

// set / unset in the same call
await channel.partialUpdateMember(user_id, {
  set: {
    key1: "new value 1",
    key2: "new value 2",
  },
  unset: ["key3"],
});

// set some fields
let memberController = ChatClient.shared.memberController(
	userId: someUserId,
	in: someChannelId
)
memberController.partialUpdate(extraData: [
	"key1": .string("value1"),
	"key2": .string("value2")
])

// unset some fields
memberController.partialUpdate(extraData: nil, unsetProperties: ["key1", "key2"])

// set / unset in the same call
memberController.partialUpdate(
	extraData: [
		"key1": .string("value1"),
		"key2": .string("value2"),
	],
	unsetProperties: ["key3"]
)

// set some fields
member, err := ch.PartialUpdateMember(ctx, members[0], PartialUpdate{
	Set: map[string]interface{}{
		"color": "red",
	},
})

// unset some fields
member, err := ch.PartialUpdateMember(ctx, members[0], PartialUpdate{
	Unset: []string{"age"},
})

// set / unset in the same call
member, err := ch.PartialUpdateMember(ctx, members[0], PartialUpdate{
	Set: map[string]interface{}{
		"color": "red",
	},
	Unset: []string{"age"},
})

$userId = "amy";

// set some fields
$response = $this->channel->updateMemberPartial($userId, ["hat" => "blue"]);

// unset some fields
$response = $this->channel->updateMemberPartial($userId, null, ["hat"]);

// set / unset in the same call
$response = $this->channel->updateMemberPartial($userId, ["hat" => "blue"], ["hat"]);

user_id = "amy"

// set some fields
response = channel.update_member_partial(user_id, to_set={"hat": "blue"})

// unset some fields
response = channel.update_member_partial(user_id, to_set=None, to_unset=["hat"])

// set / unset in the same call
response = channel.update_member_partial(user_id, to_set={"color": "red"}, to_unset=["hat"])

user_id = "amy"

// set some fields
response = channel.update_member_partial(user_id, set: { 'color' => 'red' })

// unset some fields
response = channel.update_member_partial(user_id, set: nil, unset: ['hat'])

// set / unset in the same call
response = channel.update_member_partial(user_id, set: { 'color' => 'red' }, unset: ['hat'])

// set some fields
Channel.updateMemberPartial(channel.getType(), channel.getId(), "user-1")
    .setValue("custom_key", "custom_value")
    .setValue("channel_role", "channel_moderator")
    .request();

// unset some field
Channel.updateMemberPartial(channel.getType(), channel.getId(), "user-1")
    .unsetValue("custom_key")
    .request();

// set / unset in the same call
Channel.updateMemberPartial(channel.getType(), channel.getId(), "user-1")
    .setValue("color", "red")
    .unsetValue("age")
    .request();

The queryMembers endpoint enables listing and paginating channel members. It offers filtering options to efficiently retrieve member information. This feature is particularly useful when you need to search through or display a comprehensive overview of channel membership.

Pagination and ordering

By default, members are ordered from oldest to newest and can be paginated using offset-based pagination or by the created_at or user_id fields.

While pagination by offset is the simplest to implement, it can lead to incorrect results if the list of members changes during pagination.

The recommended approach is to sort created_at or user_id for more reliable results.

await channel.queryMembers({}, sort, {});

// returns up to 100 members ordered by created_at descending
let sort = { created_at: -1 };
await channel.queryMembers({}, sort, {});

// returns up to 100 members ordered by user_id descending
sort = { user_id: -1 };
await channel.queryMembers({}, sort, {});

// paginate by user_id in descending order
sort = { user_id: 1 };
let options = { user_id_lt: lastMember.user_id };
await channel.queryMembers({}, sort, options);

// paginate by created at in ascending order
sort = { created_at: -1 };
options = { created_at_before: lastMember.created_at };
await channel.queryMembers({}, sort, options);

// paginate using offset
options = { offset: 20 };
await channel.queryMembers({}, sort, {});

// creates the controller and synchronizes the first batch of 25 members
let query = ChannelMemberListQuery(cid: channelId)
let memberListController = client.memberListController(query: query)
memberListController.synchronize()

// changing the default page size to 50
let query = ChannelMemberListQuery(cid: channelId, pageSize: 50)
let memberListController = client.memberListController(query: query)
memberListController.synchronize()

// changing the sort order by user_id in descending order
let query = ChannelMemberListQuery(cid: channelId, sort: [.init(key: .userId, isAscending: false)])
let memberListController = client.memberListController(query: query)
memberListController.synchronize()

Here’s some example of how you can query the list of members:

// query members by user.name
channel.queryMembers({'name':'tommaso'})

// autocomplete members by user name
channel.queryMembers({name:{"$autocomplete":'tomm'}})

// query member by id
channel.queryMembers({user_id:'tommaso'})

// query multiple members by id
channel.queryMembers({user_id:{'$in:'['tommaso','thierry']}})

// query channel moderators
channel.queryMembers({is_moderator:true})

// query for banned members in channel
channel.queryMembers({banned:true})

// query members with pending invites
channel.queryMembers({invite:'pending'})

// query members who joined the channel directly or accepted an invite
channel.queryMembers({joined: true})

// query members who have rejected invite or have pending invite
channel.queryMembers({joined: false}

// query all the members
channel.queryMembers({})

// order results by member created at descending
channel.queryMembers({}, {created_at:-1})

// query by user.email
client.queryMembers({ 'user.email':'awesome@getstream.io' })

// you can also query members by custom data
// subscription is a custom field
client.queryMembers({ 'subscription':'gold_plan' })

// query members by user.name
let query = ChannelMemberListQuery(cid: channelId, filter: .equal(.name, to: "tommaso"))
let memberListController = client.memberListController(query: query)
memberListController.synchronize()

// autocomplete members by user name
let query = ChannelMemberListQuery(cid: channelId, filter: .autocomplete(.name, text: "tomm"))
let memberListController = client.memberListController(query: query)
memberListController.synchronize()

// query member by id
let query = ChannelMemberListQuery(cid: channelId, filter: .equal(.id, to: "tommaso"))
let memberListController = client.memberListController(query: query)
memberListController.synchronize()

// query multiple members by id
let query = ChannelMemberListQuery(cid: channelId, filter: .in(.id, values: ["tommaso", "thierry"]))
let memberListController = client.memberListController(query: query)
memberListController.synchronize()

// query channel moderators
let query = ChannelMemberListQuery(cid: channelId, filter: .equal(.isModerator, to: true))
let memberListController = client.memberListController(query: query)
memberListController.synchronize()

// query for banned members in channel
let query = ChannelMemberListQuery(cid: channelId, filter: .equal(.banned, to: true))
let memberListController = client.memberListController(query: query)
memberListController.synchronize()

// query members who joined the channel directly or accepted an invite
let query = ChannelMemberListQuery(cid: channelId, filter: .equal(.joined, to: true))
let memberListController = client.memberListController(query: query)
memberListController.synchronize()

// query members who have rejected invite or have pending invite
let query = ChannelMemberListQuery(cid: channelId, filter: .equal(.joined, to: false))
let memberListController = client.memberListController(query: query)
memberListController.synchronize()

// you can also query members by custom data by providing a string directly
let query = ChannelMemberListQuery(cid: channelId, filter: .equal("subscription", to: "gold_plan"))
let memberListController = client.memberListController(query: query)
memberListController.synchronize()

Query Parameters

name	type	description	default	optional
filters	object	Query filters to use. You can query on any of the custom fields defined above	{}
sort	object	Sort parameters	{ created_at:1 }	✓
options	object	Pagination options	{ limit:100, offset:0 }	✓

By default when query members does not have any filter and it will match all members on your channel.

Member Queryable Built-In Fields

The following fields can be used to filter channel members, along with any custom data associated with them:

Name	Type	Description	Supported operators
id	string	User ID	$eq - $in
name	string	User name	$eq - $in - $autocomplete - $q
channel_role	string	Member role	$eq
banned	boolean	Ban status	$eq
invite	string accepted values: - pending - accepted - rejected	Invite status	$eq
joined	boolean	Whether user joined the channel or not	$eq
created_at	string (RFC3339)	Time when the member was created	$eq - $gt - $gte - $lt - $lte
updated_at	string (RFC3339)	Time when the member was updated	$eq - $gt - $gte - $lt - $lte
last_active	string (RFC3339)	Last time the member was active	$eq - $gt - $gte - $lt - $lte
cid	string	Channel CID	$eq
user.email	string	User’s email property	$eq - $in - $autocomplete

Query options

name	type	description	default	optional
limit	integer	Number of members to return	100	✓
offset	integer	Offset (max is 1000)	0	✓
user_id_lt	string	Pagination option: excludes members with ID greater or equal the value		✓
user_id_lte	string	Pagination option: excludes members with ID greater than the value		✓
user_id_gt	string	Pagination option: excludes members with ID less or equal the value		✓
user_id_gte	string	Pagination option: excludes members with ID less than the value		✓
created_at_after	string	Pagination option: select members created after the date (RFC399)		✓
created_at_before	string	Pagination option: select members created before the date (RFC399)		✓
created_at_before_or_equal	string	Pagination option: select members created before or equal the date (RFC399)		✓
created_at_after_or_equal	string	Pagination option: select members created after or equal the date (RFC399)		✓

Response

Field name	Description
Members	The list of members matching the query

Muting or Hiding Channels

Disabling Channels