Manage the user-channel membership relationship

Requires App Context

To set up and manage channel membership, you must enable App Context for your app's keyset in the Admin Portal.

When a user joins a channel or gets invited to it, a membership relationship between that user and the channel is created (Membership entity). The membership ends when this user leaves the channel.

Read on to learn how to check and update user-channel membership.

Get membership​

There are two GetMemberships() methods that return a wrapper containing a list of all channel memberships of a given user.

Both of these methods give the same output. The only difference is that you call a given method either on the User or the Channel object.

To get a list of all existing channels, use the GetChannels() method.

Method signature​

This method takes the following parameters:

  • GetMemberships() (on the User object)

    user.GetMemberships(
        string filter = "",
        string sort = "",
        int limit = 0,
        Page page = null
    )

  • GetUserMemberships() (on the Chat object)

    chat.GetUserMemberships(
        string userId,
        string filter = "",
        string sort = "",
        int limit = 0,
        Page page = null
    )

  • GetMemberships() (on the Channel object)

    channel.GetMemberships(
        string filter = "",
        string sort = "",
        int limit = 0,
        Page page = null
    )

  • GetChannelMemberships() (on the Chat object)

    chat.GetChannelMemberships(
        string channelId,
        string filter = "",
        string sort = "",
        int limit = 0,
        Page page = null
    )

Input​

ParameterRequired for GetMemberships() on UserRequired for GetUserMemberships() on ChatRequired for GetMemberships() on ChannelRequired for GetChannelMemberships() on ChatDescription
userId
Type: string
Default:
n/a
Yes
No
No
No
ID of the user for which you want to retrieve memberships.
channelId
Type: string
Default:
n/a
No
No
Yes
No
ID of the channel for which you want to retrieve memberships.
filter
Type: string
Default:
empty string
No
No
No
No
Expression used to filter the results. Returns only these memberships whose properties satisfy the given expression. The filter language is defined here.
sort
Type: string
Default:
empty string
No
No
No
No
Key-value pair of a property to sort by, and a sort direction. Available options are id, name, and updated. Use asc or desc to specify the sorting direction, or specify null to take the default sorting direction (ascending). For example: {name: "asc"}. By default, the items are sorted by the last updated date.
limit
Type: int
Default:
0
No
No
No
No
Number of objects to return in response.
page
Type: Page
Default:
null
No
No
No
No
Object used for pagination to define which previous or next result page you want to fetch.

Output​

TypeDescription
Task<MembersResponseWrapper>
An awaitable Task with the object containing the filtered, sorted, and paginated list of memberships.

Basic usage​

Find out which channels the support_agent_15 user is a member of.

  • GetMemberships() (on the User object)

    if (chat.TryGetUser("support_agent_15", out var user))
    {
        Console.WriteLine($"Found user with name {user.Name}");
        
        // Get the memberships of the user
        var memberships = await user.GetMemberships();

        Console.WriteLine($"Memberships of user {user.Name}:");

        foreach (var membership in memberships.Memberships)
        {
            Console.WriteLine($"Channel ID: {membership.ChannelId}");
        }
    }
    else
    show all 18 lines

  • GetUserMemberships() (on the Chat object)

    var userId = "support_agent_15";

    // Get the memberships of the user
    var memberships = await chat.GetUserMemberships(userId);

    Console.WriteLine($"Memberships of user with ID {userId}:");

    foreach (var membership in memberships.Memberships)
    {
        Console.WriteLine($"Channel ID: {membership.ChannelId}");
    }

  • GetMemberships() (on the Channel object)

    var userId = "support_agent_15";
    var channelName = "support";

    // retrieve the channel details
    if (chat.TryGetChannel(channelName, out var channel))
    {
        Console.WriteLine($"Found channel with name {channel.Name}");

        // get the memberships of the channel
        var memberships = await channel.GetMemberships();

        Console.WriteLine($"Memberships for channel {channel.Name}:");

        // loop through the memberships to find the user's membership
        foreach (var membership in memberships)
    show all 26 lines

  • GetChannelMemberships() (on the Chat object)

    var userId = "support_agent_15";
    var channelId = "support";

    // Get the memberships of the channel using the Chat object
    var memberships = await chat.GetChannelMemberships(channelId);

    Console.WriteLine($"Memberships for channel with ID {channelId}:");

    // Loop through the memberships to find the user's membership
    foreach (var membership in memberships.Memberships)
    {
        if (membership.UserId == userId)
        {
            Console.WriteLine($"User {userId} is a member of channel with ID {channelId}.");
        }
    show all 20 lines

Get updates​

These methods let you receive updates when specific user-channel Membership objects are added, edited, or removed on other clients:

  • SetListeningForUpdates() — listen for Membership object update information.
  • OnMembershipUpdated — add a single event handler to a single Membership object update.
  • AddListenerToMembershipsUpdate() — add a single event handler to each Membership object update from the provided list.

Method signature​

These methods take the following parameters:

  • SetListeningForUpdates

    membership.SetListeningForUpdates(bool listen)

  • OnMembershipUpdated

    // event on the Membership entity
    Action<Membership> OnMembershipUpdated;
    // needs a corresponding event handler
    void EventHandler(Membership membership)

  • AddListenerToMembershipsUpdate()

    chat.AddListenerToMembershipsUpdate(
        List<string> membershipIds, 
        Action<Membership> listener
    )

Input​

ParameterRequired in SetListeningForUpdatesRequired in OnMembershipUpdatedRequired in AddListenerToMembershipsUpdate()Description
listen
Type: bool
Default:
n/a
Yes
n/a
n/a
Whether to listen to Membership object updates.
membershipIds
Type: List<string>
Default:
n/a
No
No
Yes
List of memberships for which you want to get updates.
listener
Type: n/a
Default:
n/a
No
Yes
Yes
The definition of the custom behavior to be executed when detecting membership changes.

Output​

This method doesn't return anything.

Basic usage​

Get updates on the first user membership.

  • SetListeningForUpdates() and OnMembershipUpdated

    // reference the "support_agent_15" user
    if (chat.TryGetUser("support_agent_15", out var user))
    {
        Console.WriteLine($"Found user with name {user.Name}");
        
        // get the list of all user memberships
        var membershipsResponse = await user.GetMemberships();
        
        // extract the actual memberships from the response
        var memberships = membershipsResponse.Memberships;
        
        if (memberships.Any())
        {
            // get the first membership
            var firstMembership = memberships.First();
    show all 40 lines

Get updates on the first page of user memberships.

  • AddListenerToMembershipsUpdate()

    // reference the "support_agent_15" user
    if (chat.TryGetUser("support_agent_15", out var user))
    {
        Console.WriteLine($"Found user with name {user.Name}");
        
        // get the first page of user memberships
        var membershipsResponse = await user.GetMemberships();

        // extract the actual memberships from the response
        var memberships = membershipsResponse?.Memberships;
        
        if (memberships != null && memberships.Any())
        {
            // get the IDs of the memberships from the first page
            List<string> membershipIds = memberships.Select(m => m.Id).ToList();
    show all 37 lines

Update​

Update() updates the channel membership information for a given user.

Method signature​

This method takes the following parameters:

membership.Update(string customJsonObject)

Input​

* required
ParameterDescription
customJsonObject *
Type: string
Default:
n/a
Any custom properties or metadata associated with the channel-user membership.

Output​

An awaitable Task.

Basic usage​

Assign the premium-support role to support_agent_15 on the high-priority-incidents channel.

// reference the "support_agent_15" user
if (!chat.TryGetUser("support_agent_15", out var user))
{
    Console.WriteLine("Couldn't find user!");
    return;
};

// get the list of all user memberships and filter out the right channel
var membershipsWrapper = await user.GetMemberships(
    filter: "channel.Id == 'high-priority-incidents'"
);

if(membershipsWrapper.Memberships.Any())
{
    // add custom metadata to the user membership
show all 18 lines
Last updated on
On this page