// 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'},
]
})
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
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'}
]);
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' })
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 });
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'}
]);
There is a soft cap of 3000 channel memberships per user. If your use case requires >3000 channel memberships per user, consider removing users from channels or using elevated permissions to allow a user to access channels without membership if your use case allows.
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
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']
})
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
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 |