Channel members

LAST EDIT Oct 07 2024

Add channel members

Copied!

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

When creating a channel

Copied!

Using addMembers method

Copied!
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.

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 member custom data

Copied!

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

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

Copied!

removeMembers method allows you to remove members from a channel.

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

Leave a channel

Copied!

Users can leave a channel without moderator-level permissions.

Ensure channel members have the Leave Own Channel permission enabled.

You can familiarize yourself with all permissions in Permissions section

Add / Remove moderators to a channel

Copied!

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

Copied!

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

Remove moderators

Copied!

The demoteModerators method removes the moderator role from specified users.

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

Update channel members

Copied!

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.

Query channel members

Copied!

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

Copied!

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.

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

Query Parameters

Copied!
nametypedescriptiondefaultoptional

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

Copied!

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

Copied!
nametypedescriptiondefaultoptional
limitintegerNumber of members to return100
offsetintegerOffset (max is 1000)0
user_id_ltstring

Pagination option: excludes members with ID greater or equal the value

user_id_ltestring

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

Copied!

Field name

Description

Members

The list of members matching the query