Manage the user-channel membership relationship

Requires App Context

Enable App Context for your keyset in the Admin Portal.

A Membership entity is created when a user joins or is invited to a channel, and ends when the user leaves.

Interactive demo

Sample React app demonstrating user-channel membership.

Want to implement something similar?

Implementation guide | Source code

Test it out

Choose whether you want to join or leave a given channel and wait until you get notified when that happens.

Get members

Get all members of a channel with getMembers().

getMembers() calls App Context API and the JavaScript SDK getChannelMembers() method.

Under the hood

Method signature

This method takes the following parameters:

1channel.getMembers({
2    filter?: string,
3    sort?: object,
4    limit?: number,
5    page?: {
6        next?: string,
7        prev?: string,
8    }
9}): Promise<{
10    page: {
11        next: string;
12        prev: string;
13    };
14    total: number;
15    status: number;
16    members: Membership[];
17}>

show all 17 lines

Input

* required

Parameter	Description
filter Type: string Default: n/a	Expression used to filter the results. Returns only these members whose properties satisfy the given expression. The filtering language is defined here.
sort Type: object Default: n/a	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: number Default: 100	Number of objects to return in response. The default (and maximum) value is 100.
page Type: object Default: n/a	Object used for pagination to define which previous or next result page you want to fetch.
→ next Type: string Default: n/a	Random string returned from the server, indicating a specific position in a data set. Used for forward pagination, it fetches the next page, allowing you to continue from where you left off.
→ prev Type: string Default: n/a	Random string returned from the server, indicating a specific position in a data set. Used for backward pagination, it fetches the previous page, enabling access to earlier data. Ignored if the next parameter is supplied.

Output

Parameter	Description
Promise<> Type: object	Returned object containing these fields: page, total, status, and members.
→ page Type: object	Object used for pagination to define which previous or next result page you want to fetch.
→ next Type: string	Random string returned from the server, indicating a specific position in a data set. Used for forward pagination, it fetches the next page, allowing you to continue from where you left off.
→ prev Type: string	Random string returned from the server, indicating a specific position in a data set. Used for backward pagination, it fetches the previous page, enabling access to earlier data. Ignored if the next parameter is supplied.
→ total Type: number	Total number of channel members.
→ status Type: number	Status code of a server response, like 200.
→ members Type: Membership[]	List of all related memberships.

Sample code

List all members of the support channel on the premium support plan.

1// reference the "channel" object
2const channel = await chat.getChannel("support")
3

4// get the list of all members with the premium support plan
5await channel.getMembers({
6    filter: {"custom.support_plan == 'premium'"}
7})

Get membership

Get all channel memberships for a user with getMemberships().

getMemberships() calls App Context API and the JavaScript SDK getMemberships() method.

Under the hood

To list all channels, use getChannels() instead.

Method signature

This method takes the following parameters:

1user.getMemberships({
2    filter?: string,
3    sort?: object,
4    limit?: number,
5    page?: {
6        next?: string,
7        prev?: string
8    }
9}): Promise<{
10        page: {
11            next: string,
12            prev: string,
13        };
14        total: number,
15        status: number,
16        memberships: Membership[]
17    }>

show all 17 lines

Input

* required

Parameter	Description
filter Type: string Default: n/a	Expression used to filter the results. Returns only these memberships whose properties satisfy the given expression. The filtering language is defined here.
sort Type: object Default: n/a	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: number Default: 100	Number of objects to return in response. The default (and maximum) value is 100.
page Type: object Default: n/a	Object used for pagination to define which previous or next result page you want to fetch.
→ next Type: string Default: n/a	Random string returned from the server, indicating a specific position in a data set. Used for forward pagination, it fetches the next page, allowing you to continue from where you left off.
→ prev Type: string Default: n/a	Random string returned from the server, indicating a specific position in a data set. Used for backward pagination, it fetches the previous page, enabling access to earlier data. Ignored if the next parameter is supplied.

Output

Parameter	Description
Promise<> Type: object	Returned object containing these fields: page, total, status, and memberships.
→ page Type: any	Object used for pagination to define which previous or next result page you want to fetch.
→  → next Type: string	Random string returned from the server, indicating a specific position in a data set. Used for forward pagination, it fetches the next page, allowing you to continue from where you left off.
→  → prev Type: string	Random string returned from the server, indicating a specific position in a data set. Used for backward pagination, it fetches the previous page, enabling access to earlier data. Ignored if the next parameter is supplied.
→ total Type: number	Total number of channel memberships.
→ status Type: number	Status code of a server response, like 200.
→ memberships Type: Membership[]	List of all related memberships.

Sample code

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

1// reference the "support_agent_15" user
2const user = await chat.getUser("support_agent_15")
3

4// get the list of all user memberships
5await user.getMemberships()

Get updates

Receive updates when Membership objects are edited:

• streamUpdates() - monitors a single membership
• streamUpdatesOn() - monitors multiple memberships

Membership changes

These methods notify about field changes (metadata, status) for existing memberships, not additions or removals.

Both methods accept a callback invoked when membership data changes. They subscribe to a channel and add an objects event listener for membership events, returning an unsubscribe function.

Stream update behavior

• streamUpdates() returns the updated Membership object on each change (null if deleted)
• streamUpdatesOn() returns the complete list of monitored memberships on any change

streamUpdates() and streamUpdatesOn() call Pub/Sub API and the JavaScript SDK subscribe() and unsubscribe() methods.

Under the hood

Method signature

These methods take the following parameters:

• streamUpdates()

  1membership.streamUpdates(
  2    callback: (membership: Membership) => unknown
  3): () => void

• streamUpdatesOn()

  1static Membership.streamUpdatesOn(
  2    memberships: Membership[],
  3    callback: (memberships: Membership[]) => unknown
  4): () => void

Input

Parameter	Required in streamUpdates()	Required in streamUpdatesOn()	Description
memberships Type: Membership[] Default: n/a	No	Yes	Array of Membership objects for which you want to get updates.
callback Type: n/a Default: n/a	Yes	Yes	Callback function passed as a parameter to both methods. It defines the custom behavior to be executed when detecting membership changes.
→ membership Type: Membership Default: n/a	Yes	No	Returned Membership object with the updated data.
→ memberships Type: Membership[] Default: n/a	No	Yes	Returned array of Membership objects with the updated data.

Output

Type	Description
() => void	Function you can call to disconnect (unsubscribe) from the channel and stop receiving objects events.

Errors

Whenever a list of Membership objects is required as a parameter, and you try to get updates on membership without specifying their list, you will receive the Cannot stream membership updates on an empty list error.

Sample code

Get updates on the first user membership.

• streamUpdates()

  1const { memberships } = await chat.currentUser.getMemberships()
  2const membership = memberships[0]
  3membership.streamUpdates((membership) => {
  4    // The callback receives the entire updated Membership object each time a change occurs.
  5    if (membership) {
  6        console.log("Updated membership: ", membership)
  7    } else {
  8        console.log("Membership was deleted")
  9    }
  10})

Get updates on the first page of user memberships.

• streamUpdatesOn()

  1const { memberships } = await chat.currentUser.getMemberships()
  2Membership.streamUpdatesOn(memberships, (memberships) => {
  3    // The callback receives the complete list of all memberships you're monitoring
  4    // each time any change occurs.
  5    console.log("Updated memberships: ", memberships)
  6})

Other examples

Stop listening to updates on the first user membership.

• streamUpdates()

  1const { memberships } = await chat.currentUser.getMemberships()
  2const membership = memberships[0]
  3const stopUpdates = membership.streamUpdates(/* handle update callback */)
  4// after some time...
  5stopUpdates()

Stop listening to updates on the first page of user memberships.

• streamUpdatesOn()

  1const { memberships } = await chat.currentUser.getMemberships()
  2const stopUpdates = Membership.streamUpdatesOn(memberships, /* handle update callback */)
  3// after some time...
  4stopUpdates()

Update

Update a user's channel membership information with update().

update() calls App Context API and the JavaScript SDK setMemberships() method.

Under the hood

Method signature

This method takes the following parameters:

1membership.update({
2    custom: ObjectCustom
3}): Promise<Membership>

Input

* required

Parameter	Description
custom * Type: ObjectCustom Default: n/a	Any custom properties or metadata associated with the channel-user membership.

Output

Type	Description
Promise<Membership>	Returned (modified) object containing all membership data.

Errors

If you try to update a membership that doesn't exist, you will receive the No such membership exists error.

Sample code

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

1// reference the "support_agent_15" user
2const user = await chat.getUser("support_agent_15")
3

4// get the list of all user memberships and filter out the right channel
5const membership = await user.getMemberships({
6    filter: "channel.id == 'high-priority-incidents'"
7})
8

9// add custom metadata to the user membership
10await membership.update({
11        custom: {role: "premium-support"}
12})