Channel Members

Channel members are users who have been added to a channel and can participate in conversations. This page covers how to manage channel membership, including adding and removing members, controlling message history visibility, and managing member roles.

Adding and Removing Members

Adding Members

Using the addMembers() method adds the given users as members to a channel.

await channel.addMembers(["thierry", "josh"]);

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

Members can also be added when creating a channel:

val channelClient = client.channel("messaging", "general")

// Add members during channel creation
channelClient.create(
  memberIds = listOf("james_bond", "alec_trevelyan", "bill_fairbanks"),
  extraData = emptyMap(),
).enqueue()

// Add members with custom extra data during channel creation
val params = CreateChannelParams(
  members = listOf(
    MemberData(userId = "james_bond", extraData = mapOf("code_name" to "007")),
    MemberData(userId = "alec_trevelyan", extraData = mapOf("code_name" to "006")),
  ),
  extraData = emptyMap(),
)
channelClient.create(params).enqueue()

Removing Members

Using the removeMembers() method removes the given users from the channel.

await channel.removeMembers(["tommaso"]);

Leaving a Channel

Users can leave a channel without moderator-level permissions. Ensure channel members have the Leave Own Channel permission enabled.

channelClient.removeMembers(listOf("my_user_id")).enqueue()

You can familiarize yourself with all permissions in the Permissions section.

Hide History

When members join a channel, you can specify whether they have access to the channel’s message history. By default, new members can see the history. Set hide_history to true to hide it for new members.

// Add members by their IDs with hideHistory=true
channelClient.addMembers(
  memberIds = listOf("thierry"),
  hideHistory = true,
).enqueue()

// Add members by their IDs with hideHistory=true and custom extra data
val params = AddMembersParams(
  members = listOf(
    MemberData(userId = "thierry", extraData = mapOf("new_member" to true)),
  ),
  hideHistory = true,
)
channelClient.addMembers(params).enqueue()

Hide History Before a Specific Date

Alternatively, hide_history_before can be used to hide any history before a given timestamp while giving members access to later messages. The value must be a timestamp in the past in RFC 3339 format. If both parameters are defined, hide_history_before takes precedence over hide_history.

final cutoff = DateTime.now().subtract(Duration(days: 7)); // Last 7 days

await channel.addMembers(
  ["thierry"],
  hideHistoryBefore: cutoff,
);

System Message Parameter

You can optionally include a message object when adding or removing members that client-side SDKs will use to display a system message. This works for both adding and removing members.

val channelClient = client.channel("messaging", "general")

// Add members with a system message
channelClient.addMembers(
  listOf("thierry", "josh"),
  Message(text = "Thierry and Josh joined this channel."),
).enqueue()

// Add members with custom extra data and a system message
val params = AddMembersParams(
  members = listOf(
    MemberData(userId = "thierry", extraData = mapOf("new_member" to true)),
    MemberData(userId = "josh", extraData = mapOf("new_member" to true)),
  ),
  systemMessage = Message(text = "Thierry and Josh joined this channel."),
)
channelClient.addMembers(params).enqueue()

// Remove member with a system message
channelClient.removeMembers(
  listOf("tommaso"),
  Message(text = "Tommaso was removed from this channel."),
).enqueue()

Adding and Removing Moderators

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

await channel.addModerators(["thierry", "josh"]);

Remove Moderators

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

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

Member Custom Data

Custom data can be added at the channel member level. This is useful for storing member-specific information that is separate from user-level data. Ensure custom data does not exceed 5KB.

Adding Custom Data

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

Updating Member Data

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.updateMemberPartial(
  {
    set: {
      key1: "new value 1",
      key2: "new value 2",
      channel_role: "channel_moderator",
    },
  },
  { userId: "jane" },
);

// Unset some fields
await channel.updateMemberPartial(
  {
    unset: ["key1", "key2"],
  },
  { userId: "jane" },
);

// Set and unset in the same call
await channel.updateMemberPartial(
  {
    set: {
      key1: "new value 1",
      key2: "new value 2",
    },
    unset: ["key3"],
  },
  { userId: "jane" },
);
Previous
Channel Pagination
Next
Channel Management