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:

• Create and send custom events when invitations are sent
• Let invited users receive these events

Invite one user

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

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

Under the hood

Method signature

This method takes the following parameters:

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

Input

* required

Parameter	Description
user * Type: User Default: n/a	User that you want to invite.

Output

Type	Description
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.

inviteMultiple() calls App Context API and the JavaScript SDK setChannelMembers() method that sets a maximum limit of 100 to a number of user-channel memberships that can be updated in one call.

Under the hood

Method signature

This method takes the following parameters:

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

Input

* required

Parameter	Description
users * Type: User[] Default: n/a	List of users you want to invite to the group channel. You can invite up to 100 users in one call.

Output

Type	Description
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).

getInvitees() calls App Context API and the JavaScript SDK getChannelMembers() method, filtering results to members with a pending status.

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

* required

Parameter	Description
params Type: object Default: n/a	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: n/a	Object used for pagination (next/prev cursors).
params.filter Type: string Default: n/a	Expression used to filter the results. This filter is combined with the pending status filter.
params.sort Type: object Default: n/a	Key-value pairs for result sorting.

Output

Type	Description
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

Parameter	Description
callback * Type: (invite: Invite) => void Default: n/a	Function invoked with an Invite event whenever the user receives a channel invitation.

The Invite object contains:

Property	Description
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

Type	Description
() => void	Function 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()