Invite users to channels

Requires App Context

Enable App Context for your keyset in the Admin Portal.

Invite users to private or group conversations, creating their channel membership. Invitations trigger an invite event that you can listen to and notify invited users.

To send notifications on invitations, implement custom logic to:

Invite one user​

Request a user to join a channel with invite().

icon

Under the hood

Method signature​

This method takes the following parameters:

1channel.invite(user: User): Promise<Membership>

Input​

required
user required#
Type: User
Default: no default
User that you want to invite.

Output​

TypeDescription
Promise<Membership>Returned (modified) object containing the membership data.

Sample code​

Invite support-agent-15 to join the high-prio-incidents channel.

1// reference "support-agent-15"
2const user = await chat.getUser("support_agent_15")
3
4// reference the "high-prio-incidents" channel
5const channel = await chat.getChannel("high-prio-incidents")
6
7// invite the agent to join the channel
8await channel.invite(user)

Invite multiple users​

Request multiple users to join a channel with inviteMultiple(). Maximum 100 users per call.

icon

Under the hood

Method signature​

This method takes the following parameters:

1channel.inviteMultiple(users: User[]): Promise<Membership[]>

Input​

required
users required#
Type: User[]
Default: no default
List of users you want to invite to the group channel. You can invite up to 100 users in one call.

Output​

TypeDescription
Promise<Membership[]>Returned (modified) list of objects containing the membership data.

Sample code​

Invite support-agent-15 and support-agent-16 to join the high-prio-incidents channel.

1// reference both agents
2const user1 = await chat.getUser("support_agent_15")
3const user2 = await chat.getUser("support_agent_16")
4
5// reference the "high-prio-incidents" channel
6const channel = await chat.getChannel("high-prio-incidents")
7
8// invite both agents to join the channel
9await channel.inviteMultiple([
10 user1,
11 user2
12])

Get invitees​

getInvitees() returns the list of channel members whose membership status is "pending" (invited but not yet joined).

icon

Under the hood

Method signature​

This method takes the following parameters:

1channel.getInvitees(params?: Omit<AppContext.GetMembersParameters, "channel" | "include">): Promise<{
2 page: {
3 next: string | undefined;
4 prev: string | undefined;
5 };
6 total: number | undefined;
7 status: number;
8 members: Membership[];
9}>

Input​

params#
Type: object
Default: no default
Optional pagination and filtering parameters. Same shape as getMembers().
params.limit#
Type: number
Default: 100
Number of objects to return in response. The default (and maximum) value is 100.
params.page#
Type: object
Default: no default
Object used for pagination (next/prev cursors).
params.filter#
Type: string
Default: no default
Expression used to filter the results. This filter is combined with the pending status filter.
params.sort#
Type: object
Default: no default
Key-value pairs for result sorting.

Output​

TypeDescription
Promise<{page, total, status, members}>Object containing only pending (invited) members. Has the same structure as the response from getMembers().

Sample code​

Get all pending invitees for the high-prio-incidents channel.

1// reference the "high-prio-incidents" channel
2const channel = await chat.getChannel("high-prio-incidents")
3
4// get members with pending (invited) status
5const { members } = await channel.getInvitees()
6
7members.forEach((membership) => {
8 console.log("Pending invitee:", membership.user.id)
9})

Listen to invite events​

Monitor invitation events with onInvited() on the User object. This replaces the deprecated listenForEvents() approach with a typed callback.

Deprecated method

listenForEvents({ type: "invite" }) is deprecated. Use user.onInvited() instead, which provides a typed Invite object with richer data.

Method signature​

1user.onInvited(callback: (invite: Invite) => void): () => void

Input​

required
callback required#
Type: (invite: Invite) => void
Default: no default
Function invoked with an Invite event whenever the user receives a channel invitation.

The Invite object contains:

channelId#
Type: string
The channel the user is invited to.
channelType#
Type: ChannelType
Type of the channel (direct, group, etc.).
invitedByUserId#
Type: string
User ID of who sent the invitation.
invitationTimetoken#
Type: string
Timetoken of the invitation.

Output​

TypeDescription
() => voidFunction you can call to stop receiving invitation events.

Sample code​

1const user = chat.currentUser
2
3const stopListening = user.onInvited((invite) => {
4 console.log(`Invited to channel ${invite.channelId} (${invite.channelType}) by ${invite.invitedByUserId}`)
5})
6
7// stop listening:
8// stopListening()

Was this page useful?

Last updated on