How to manage channel invitations in Sendbird Chat
Introduction
Channel invitations are an essential feature of Sendbird Chat. This allows users or your application server to control the membership of private and public group chats. It also allows users to inquire about their channel membership. This guide dives deep into the topic and provides information about all the available options and events.
This guide covers general information about channel invitations, channel creation, private group channel invitations, and how to accept/decline invitations manually.
Let’s begin! 💻
General information
Channel invitations govern channel membership. Users become members of a private group channel in a couple of ways:
- At the time of channel creation, it is possible to pass in an array of up to 100 user IDs to become members of the channel.
- After channel creation, it is also possible to invite up to 100 users per request.
You can implement channel invitations through a Sendbird Chat SDK or the Platform API. This guide explores both options.
Before diving into the implementation details, look at the table below. It depicts invitation approaches and the associated methods for different platforms.
| Invitation approach | Platform | Method |
| Upon private group channel creation | Android | groupChannelParams
GroupChannel.createChannel(groupchannelParams) |
| iOS | groupChannelParams
GroupChannel.createChannelWithParams(groupchannelParams) | |
| JavaScript | groupChannelParams
GroupChannel.createChannel(groupchannelParams) | |
| Platform API | POST v3/group_channels/ | |
| After private group channel creation | Android | groupchannel.inviteWithUserIds() |
| iOS | groupchannel.inviteUserIds() | |
| JavaScript | groupchannel.inviteWithUserIds() | |
| Platform API | POST v3/groups_channels/CHANNEL_URL/invite |
Users can inquire about their membership status in private and public group channels in the following ways:
- A user can retrieve a list of channels they were automatically added to by invitation (default behavior)
- By creating a channel list query instance, a user can retrieve a list of channels to which they’ve been invited.
The following table contains more information.
| Invited status approach | Platform | Method |
| Fetch channels I’m a member of | Android | GroupChannel.createMyGroupChannelListQuery() |
| iOS | SBDGroupChannel.createMyGroupChannelListQuery() | |
| JavaScript | sb.GroupChannel.createMyGroupChannelListQuery() | |
| Platform API | GET /v3/users/{user_id}/my_group_channels | |
| Fetch channels where my membership status is filtered | Android | GroupChannelListQuery + setMemberStateFilter |
| iOS | SBDGroupChannelListQuery + SBDMemberStateFilter | |
| JavaScript | GroupChannelListQuery + MemberStateFilter | |
| Platform API | member_state_filter | |
| Filters | Returned channels | |
| INVITED | Invitations have been sent to the current User (but not accepted yet) | |
| INVITED_BY_FRIEND | Invitations from a friend have been sent to the current User (but not accepted yet) | |
| INVITED_BY_NON_FRIEND | Invitations from a non-friend have been sent to the current User (but not accepted yet) | |
| JOINED | Channels the current user is already a member of | |
| Check my membership status within the current channel | Android | GroupChannel.getMyMemberState() |
| iOS | SBDGroupChannel.myMemberState | |
| JavaScript | N/A | |
Now that we have covered the basics, let’s talk about creating channels in Sendbird.
Creating channels in Sendbird using an SDK or Platform API
Creating private group channels with either the Sendbird SDK or Platform API boils down to one main difference. On the one hand, with channels created via the SDK, users have the freedom to chat and send channel invitations to whomever they like. On the other hand, your backend controls which users chat to whom, using the Platform API.
Note that batches of up to 100 users can be invited to a private group channel at the point of creation. Batches of up to 100 users can be invited at a later point, up to a maximum channel membership of 100 members. If you need to increase the maximum channel membership size, please reach out to your account manager or send us a request.
Now let’s talk about creating channels using either the SDK or Platform API.
Creating channels using a Sendbird Chat SDK
By default, creating a channel via a Sendbird SDK gives users the freedom to start chatting with any other user as long as they know that user’s ID. Apps that are social in nature, build community, or depend on a user’s freedom to engage socially with other users will likely implement channel invitations through the SDK.
Note: For Sendbird’s private group channels, the option to auto-accept invitations is “on” by default. For Sendbird’s public group channels, no invitation is needed.
When auto-accept invitations is “on,” the created channel will appear in the invited user’s channel list by default (if there are no messages, the invited user will need to add the filter to include empty channels). The invited user will also receive notifications and messages from the created channel.
Events
Creating a channel with the SDK automatically triggers the following events:
| Event type | Event | Note |
| Channel event handler (event delegate in iOS) | onUserJoined() | One event for each user in the member list |
| onMessageReceived() | If auto-generated admin messages are turned on (default: off) | |
| Webhooks | group_channel:create
group_channel:join | If auto-accept invitations is turned on (default: on) |
| group_channel:create | If auto-accept invitations is turned off | |
| Auto-generated admin messages (if: “on”) | Message is sent.“The channel is created.“ | The message contains channel details and the user objects of each member |
How to block channel creation through the SDK
Sendbird provides an ACL setting that prevents channel creation from all Sendbird SDKs.
Creating channels via Platform API
Creating a channel using the Platform API gives your backend full control to determine when to create a channel and to specify which users belong to that channel.
Remember that users in the SDK may not start a chat with other users until you create a channel containing other users. Using the Platform API lets you fully control which users chat with whom. Apps that coordinate conversations according to discrete transactions, tasks, support tickets, or consultations will likely implement channel invitations through the Platform API.
Note: Creating a channel using a Platform API call will always add to the channel the users that were invited at the channel’s creation, regardless of the global invitation acceptance settings.
Events
Creating a channel with the Platform API automatically triggers the following events:
| Event type | Event | Note |
| Channel event handler (event delegate in iOS) | onUserJoined() | One event for each user in the member list |
| onMessageReceived() | If auto-generated admin messages are turned on (default: off) | |
| Webhooks | group_channel:create
group_channel:join | If auto-accept invitations is turned on (default: on). Whether auto-accept invitations is turned off or on, calls to create a channel using the Platform API will always add users to the channel that were invited at the channel’s creation. |
| Auto-generated admin messages (if: “on”) | Message is sent.“The channel is created.“ | The message contains channel details and the user objects of each member |
Private group channels: Post-channel creation invitations explained
Whether invitations are accepted automatically or accepted and declined manually determines the behavior of channel invitations and how a user joins a channel. This section explains both options: auto-accept invitation and manual accept/decline invitation.
Auto-accept invitation
In this section, we’ll talk about events that occur when the auto-accept invitations option is turned “on.”
By default, if User A invites User B to a channel (groupChannel.invite()), at the moment of invitation, User B automatically accepts the invitation and becomes a member of that channel. At channel creation in both the Sendbird SDK and Platform API, you can pass a list of up to 100 user IDs to invite to a group channel. All invitations are automatically created and accepted by the list of invited users. By default, auto-accept invitations is “true” if the invitation is sent through the SDK invite method or the Platform API endpoint (v3/groups_channels/CHANNEL_URL/invite).
Events
Making an invitation and automatically accepting the invitation creates events that trigger at the same time: (Note: Sendbird’s default behavior is to accept invitations automatically)
| Event type | Event | Note |
| Channel event handler (event delegate in iOS) | onUserReceivedInvitation() | |
| onUserJoined() | ||
| Webhooks | group_channel:invite | |
| group_channel:join | Contains a list of joined users | |
| Auto-generated admin messages (if: “on”) | USER_JOINED | Contains a list of joining users |
Manual accept/decline invitation
This section provides details about events that occur when the auto-accept invitations option is turned “off.”
By default, users are automatically added to private group channels when they are invited. You can alter this default behavior for individual users or globally via the Platform API.
When the user is created, the global setting determines a user’s individual invitation preference. It’s important to note that a user’s personal preference does not change when the global setting changes. To apply the global setting change to all current users, update all current user profiles individually.
When the auto-accept invitations option is turned “off”, the following occurs: When User A invites User B, User B can decide to accept or decline the invitation.
Even when the auto-accept invitations option is turned “off,” invitations are automatically created for the passed list of user IDs when a group channel is created either via Sendbird SDK or Platform API.
Note: Users will automatically become members of a channel if the channel is created via the Platform API with a passed list of user IDs. There will be no invitations. If invitations are required, create the channel first and then invite the users in bulk.
Once User A invites User B, then User B will be added to a private channel’s member list with the status of “invited” in the member list object of the group channel.
- As an invited member, they will be able to see the channel, but not take any action on it aside from being able to call:
- If User B accepts the invitation, then User B becomes a member of the channel
- If User B declines the invitation, then the invitation is revoked
- User B can fetch their invited channels using a myChannelListQuery and applying MemberStateFilter
Events
Creating a Sendbird group channel and passing in an array of user IDs will trigger the following events:
| Event type | Event |
| Channel event handler (event delegate in iOS) | N/A |
| Webhooks | group_channel:create |
| Auto-generated admin messages (if: “on”) | Type: CHANNEL_CREATE |
Making an invitation from a Sendbird SDK using groupChannel.invite() with the auto-accept option turned “off” triggers these events:
| Event type | Event |
| Channel event handler (event delegate in iOS) | onUserReceivedInvitation() |
| Webhooks | group_channel:invite |
| Auto-generated admin messages (if: “on”) | N/A |
Accept/decline invitation
Once an invitation has been sent, expect individual invitations to be accepted or declined. One event is triggered for each user accepting or declining invitations.
| Event type | Event |
| Channel event handler (event delegate in iOS) | onUserAcceptedInvitation() |
| onUserDeclinedInvitation() | |
| Webhooks | group_channel:join |
| group_channel:decline_invite | |
| Auto-generated admin messages (if: “on”) | Type: USER_JOINED |
Public group channels and open channels
Public group channels are used mostly for cases in which one user shares a channel with another user, and the chat is transparent and public. A passphrase can be applied if needed.
Open channels are ideal for live events where massive membership is needed, but there is no need to maintain membership.
Sendbird’s public group channels and open channels do not require invitations to join. Public group channels maintain membership once joined. Open channels have a temporary membership held for as long as as a user has entered the channel, not exited the channel, and remains online.
Example scenario for a manual accept/decline invitation
Let’s assume that the auto-accept invitations option has been turned “off” globally. User A creates a new Sendbird group channel in your app, or User A is already a member of a group channel, and wants to invite other users to that channel in your app. In this example, User A shares the group channel link in WhatsApp.
- Given
- User A has copied a deep link to a Sendbird channel
- The deep link contains information to open your app
- The deep link contains a channel URL to which User B is invited
- User A has sent the link in WhatsApp
- User B is already a user of your app but not a member of the group channel
- Then
- When User B clicks the deep link, your app should open
- Then User B’s device retrieves the channel object to which they are invited by using the channel URL
- User B is presented with the option to accept or decline the invitation
Conclusion
The channel invitations feature determines how your users will interact with each other and with your company. Will users freely and socially interact with others or will your app set up conversations among users?
Given the practical repercussions of this crucial feature, Sendbird ensures that channel invitations are as flexible as possible: from channel creation invitations to auto-accept and manual accept to implementation with a Sendbird Chat SDK or Platform API.
Feel free to reach out to us if you need technical help with your app, and share with us what you’re building! Happy coding! 👩💻
