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().

Method signature

This method takes the following parameters:

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

Input

* required

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

Output

Type	Description
PNFuture<Membership>	Returned (modified) object containing the membership data.

Sample code

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

1// assuming you have a chat service or a chat client object called "chat"
2val userId = "support-agent-15"
3val channelId = "high-prio-incidents"
4// reference "support-agent-15"
5chat.getUser(userId).async { userResult ->
6    userResult.onSuccess { user ->
7        if (user != null) {
8            // User found, proceed to get the "high-prio-incidents" channel
9            chat.getChannel(channelId).async { channelResult ->
10                channelResult.onSuccess { channel ->
11                    if (channel != null) {
12                        // Channel found, proceed to invite the agent to join the channel
13                        channel.invite(user).async { inviteResult ->
14                            inviteResult.onSuccess { membership ->
15                                // User successfully invited
16                                println("User ${user.id} has been invited to channel ${channel.id}")
17                            }.onFailure {
18                                // handle failure
19                            }
20                        }
21                    }
22                }.onFailure {
23                    // handle failure
24                }
25            }
26        }
27    }.onFailure {
28        // handle failure
29    }
30}

show all 30 lines

Invite multiple users

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

Method signature

This method takes the following parameters:

1channel.inviteMultiple(users: Collection<User>): PNFuture<List<Membership>>

Input

* required

Parameter	Description
users * Type: Collection<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
PNFuture<List<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.

// assuming you have a chat service or a chat client object called "chat", reference both agents and the "high-prio-incidents" channel
val userId1 = "support-agent-15"
val userId2 = "support-agent-16"
val channelId = "high-prio-incidents"


chat.getUser(userId1).async { userResult1 ->
    userResult1.onSuccess { user1 ->
        if (user1 != null) {
            // First user found, now get the second user
            chat.getUser(userId2).async { userResult2 ->
                userResult2.onSuccess { user2 ->
                    if (user2 != null) {
                        // Second user found, now get the channel
                        chat.getChannel(channelId).async { channelResult ->
                            channelResult.onSuccess { channel ->
                                if (channel != null) {
                                    // Channel found, proceed to invite both users
                                    channel.inviteMultiple(listOf(user1, user2)).async { inviteResult ->
                                        inviteResult.onSuccess { memberships ->
                                            // Users successfully invited
                                            println("Users ${user1.id} and ${user2.id} have been invited to channel ${channel.id}")
                                        }.onFailure {
                                            // handle failure
                                        }
                                    }
                                }
                            }.onFailure {
                                // handle failure
                            }
                        }
                    }
                }.onFailure {
                    // handle failure
                }
            }
        }
    }.onFailure {
        // handle failure
    }
}

show all 40 lines

Get invitees

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

Method signature

This method takes the following parameters:

1channel.getInvitees(
2    limit: Int? = 100,
3    page: PNPage? = null,
4    filter: String? = null,
5    sort: Collection<PNSortKey<PNMemberKey>> = listOf(),
6): PNFuture<MembersResponse>

Input

* required

Parameter	Description
limit Type: Int? Default: 100	Number of objects to return in response. The default (and maximum) value is 100.
page Type: PNPage? Default: null	Object used for pagination to define which previous or next result page you want to fetch.
filter Type: String? Default: null	Expression used to filter the results. This filter is combined with the pending status filter.
sort Type: Collection<PNSortKey<PNMemberKey>> Default: listOf()	A collection to specify the sort order.

Output

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

1val channelId = "high-prio-incidents"
2

3chat.getChannel(channelId).async { channelResult ->
4    channelResult.onSuccess { channel ->
5        if (channel != null) {
6            channel.getInvitees().async { result ->
7                result.onSuccess { membersResponse ->
8                    membersResponse.members.forEach { membership ->
9                        println("Pending invitee: ${membership.user.id}")
10                    }
11                }.onFailure {
12                    // handle failure
13                }
14            }
15        }
16    }.onFailure {
17        // handle failure
18    }
19}

show all 19 lines

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<EventContent.Invite>() is deprecated. Use user.onInvited() instead, which provides a typed Invite object with richer data.

Method signature

This method has the following parameters:

1user.onInvited(callback: (invite: Invite) -> Unit): AutoCloseable

Input

* required

Parameter	Description
callback * Type: (invite: Invite) -> Unit 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: Long	Timetoken of the invitation.

Output

Type	Description
AutoCloseable	Interface that lets you stop receiving invitation events by invoking the close() method.

Sample code

Listen for invite events on the current user.

1val user = chat.currentUser
2

3val subscription = user.onInvited { invite ->
4    println("Invited to channel ${invite.channelId} (${invite.channelType}) by ${invite.invitedByUserId}")
5}
6

7// stop listening:
8// subscription.close()