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

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

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.

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.

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" }]);

Remove channel members / Leave a channel

Remove channel members

removeMembers method allows you to remove members from a channel.

await channel.removeMembers(["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"]);

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
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();

Query channel members

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, {});

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 Parameters

nametypedescriptiondefaultoptional
filtersobjectQuery filters to use. You can query on any of the custom fields defined above{}
sortobjectSort parameters{ created_at:1 }✓
optionsobjectPagination 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:

NameTypeDescriptionSupported operators
idstringUser ID$eq - $in
namestringUser name$eq - $in - $autocomplete - $q
channel_rolestringMember role$eq
bannedbooleanBan status$eq
invitestring accepted values: - pending - accepted - rejectedInvite status$eq
joinedbooleanWhether user joined the channel or not$eq
created_atstring (RFC3339)Time when the member was created$eq - $gt - $gte - $lt - $lte
updated_atstring (RFC3339)Time when the member was updated$eq - $gt - $gte - $lt - $lte
last_activestring (RFC3339)Last time the member was active$eq - $gt - $gte - $lt - $lte
cidstringChannel CID$eq
user.emailstringUser’s email property$eq - $in - $autocomplete

Query options

nametypedescriptiondefaultoptional
limitintegerNumber of members to return100✓
offsetintegerOffset (max is 1000)0✓
user_id_ltstringPagination option: excludes members with ID greater or equal the value✓
user_id_ltestringPagination option: excludes members with ID greater than the value✓
user_id_gtstringPagination option: excludes members with ID less or equal the value✓
user_id_gtestringPagination option: excludes members with ID less than the value✓
created_at_afterstringPagination option: select members created after the date (RFC399)✓
created_at_beforestringPagination option: select members created before the date (RFC399)✓
created_at_before_or_equalstringPagination option: select members created before or equal the date (RFC399)✓
created_at_after_or_equalstringPagination option: select members created after or equal the date (RFC399)✓

Response

Field nameDescription
MembersThe list of members matching the query
Previous
Muting or Hiding Channels
Next
Disabling Channels
© Getstream.io, Inc. All Rights Reserved.