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.

Interactive demo

Check how a sample implementation could look like in a React app showcasing user-channel membership.

Want to implement something similar?

Read how to do that or go straight to the demo's 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

getMembers() returns the list of all channel members.

Under the hood

Method signature

This method takes the following parameters:

channel.getMembers({
    filter?: string,
    sort?: object,
    limit?: number,
    page?: {
        next?: string,
        prev?: string,
    }
}): Promise<{
    page: {
        next: string;
        prev: string;
    };
    total: number;
    status: number;
show all 17 lines

Input

Parameter	Type	Required	Default	Description
`filter`	`string`	No	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`	`object`	No	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`	`number`	No	`100`	Number of objects to return in response. The default (and maximum) value is `100`.
`page`	`object`	No	n/a	Object used for pagination to define which previous or next result page you want to fetch.
→ `next`	`string`	No	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`	`string`	No	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	Type	Description
`Promise<>`	`object`	Returned object containing these fields: `page`, `total`, `status`, and `members`.
→ `page`	`object`	Object used for pagination to define which previous or next result page you want to fetch.
→ `next`	`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`	`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`	`number`	Total number of channel members.
→ `status`	`number`	Status code of a server response, like `200`.
→ `members`	`Membership[]`	List of all related memberships.

Basic usage

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

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

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

Get membership

getMemberships() returns the list of all channel memberships of a given user.

Under the hood

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

Method signature

This method takes the following parameters:

user.getMemberships({
    filter?: string,
    sort?: object,
    limit?: number,
    page?: {
        next?: string,
        prev?: string
    }
}): Promise<{
        page: {
            next: string,
            prev: string,
        };
        total: number,
        status: number,
show all 17 lines

Input

Parameter	Type	Required	Default	Description
`filter`	`string`	No	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`	`object`	No	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`	`number`	No	`100`	Number of objects to return in response. The default (and maximum) value is `100`.
`page`	`object`	No	n/a	Object used for pagination to define which previous or next result page you want to fetch.
→ `next`	`string`	No	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`	`string`	No	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	Type	Description
`Promise<>`	`object`	Returned object containing these fields: `page`, `total`, `status`, and `memberships`.
→ `page`	`any`	Object used for pagination to define which previous or next result page you want to fetch.
→ → `next`	`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`	`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`	`number`	Total number of channel memberships.
→ `status`	`number`	Status code of a server response, like `200`.
→ `memberships`	`Membership[]`	List of all related memberships.

Basic usage

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

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

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

Get updates

You can receive updates when specific user-channel Membership object(s) are added, edited, or removed using the following methods:

streamUpdates() checks updates on a single Membership object.
streamUpdatesOn() checks updates on a list of Membership objects.

Both methods accept a callback function as an argument. The Chat SDK invokes this callback whenever someone adds, changes, or removes membership data.

Underneath, these methods subscribe the current user to a channel and add an objects event listener to receive all objects events of type membership. These methods also return the unsubscribe function you can invoke to stop receiving objects events and unsubscribe from the channel.

Under the hood

Method signature

These methods take the following parameters:

streamUpdates()

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

streamUpdatesOn()

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

Input

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

Basic usage

Get updates on the first user membership.

streamUpdates()

const { memberships } = await chat.currentUser.getMemberships()
const membership = memberships[0]
membership.streamUpdates((membership) => {
    console.log("Updated membership: ", membership)
})

Get updates on the first page of user memberships.

streamUpdatesOn()

const { memberships } = await chat.currentUser.getMemberships()
Membership.streamUpdatesOn(memberships, (memberships) => {
    console.log("Updated memberships: ", memberships)
})

Other examples

Stop listening to updates on the first user membership.

streamUpdates()

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

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

streamUpdatesOn()

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

Update

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

Under the hood

Method signature

This method takes the following parameters:

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

Input

Parameter	Type	Required	Default	Description
`custom`	`ObjectCustom`	Yes	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.

Basic usage

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

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

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

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

Requires App Context

Interactive demo​

Want to implement something similar?

Test it out​

Get members​

Under the hood

Method signature​

Input​

Output​

Basic usage​

Get membership​

Under the hood

Method signature​

Input​

Output​

Basic usage​

Get updates​

Under the hood

Method signature​

Input​

Output​

Errors​

Basic usage​

Other examples​

Update​

Under the hood

Method signature​

Input​

Output​

Errors​

Basic usage​

Interactive demo

Test it out

Get members

Method signature

Input

Output

Basic usage

Get membership

Method signature

Input

Output

Basic usage

Get updates

Method signature

Input

Output

Errors

Basic usage

Other examples

Update

Method signature

Input

Output

Errors

Basic usage