feat: `Community` #2531

alechkos · 2023-09-23T02:46:17Z

By default, a community consists of two components: the parent group and its default subgroup, which serves as an announcement group. The default subgroup is represented by an instance of GroupChat as it functions like a typical "closed" group. The parent group, however, is an instance of the Community class, and all community-related operations are carried out on it.

The Community class extends the GroupChat class, making all the methods available to the Community class as well.

You can simply retrieve a parent group object or its subgroup object.

Updated events to support communities:
- group_join event: is now emitted also when a user joins community linked subgroups
- group_admin_changed event: is now emitted also when a user is promoted/demoted in community linked subgroups
Added new methods:
- Client.createCommunity that takes required parameter title and can also take an optional object options with properties:
  - description for a community description
  - subGroupIds for linking these groups to the community at a time of its creation
  - membershipApprovalMode, false by default
  - allowNonAdminSubGroupCreation, false by default
- Community.linkSubgroups that takes a single group ID or an array of group IDs to link to the community
- Community.unlinkSubgroups, the same as previous but for group unlinking, can also take an optional object options with a boolean property removeOrphanMembers (false by default). If true, the method will remove specified subgroups from the community along with their members who are not part of any other subgroups within the community
- Client.joinSubgroup and Community.joinSubgroup methods to join a community subgroup by community ID and a subgroup ID
- Community.promoteParticipants and Community.demoteParticipants now supports communities
- Community.removeParticipants method now supports communities
  
  NOTE:
  Removing participant from the community will remove them also from all its linked groups
- Community.getParticipants method to retrieve community participants
  
  NOTE:
  To get the full result, you need to be a community admin.
  Otherwise, you will only get the participants that a regular community member can see
- Community.getSubgroups method to retrieve the list of community subgroups
- Community.getJoinedSubgroups method to retrieve the community subgroups the current user is a member of
- Community.getUnjoinedSubgroups method to retrieve all community subgroups in which the current user is not yet a member, preferable to use in a case when the current user is not a community owner/admin but only a member, otherwise, the result will be an empty array
- Community.setNonAdminSubGroupCreation method that sets who can add groups to the community (only admins or all members)
- Client.deactivateCommunity and Community.deactivate methods for community creators
  
  NOTE:
  The method is only for community owners/admins to allow them to delete the community
  Community admins can't deactivate the community, but can only leave it,
  while community creators can't leave the community but can only deactivate it instead
- Community.leave method now supports communities
  
  NOTE:
  If you're community admin or a regular member, you can leave the community by leaving through its parent group
  or also through its default subgroup

Related Issues

The PR closes #2533, closes #2483

Usage Example

1. To get the community object (the parent group, is an instance of `Community`):

let community;
community = await client.getChatById('[email protected]');
// OR
[community] = (await client.getChats()).filter(chat => chat.isCommunity && chat.name === 'CommunityName');
/**
 * The example output of the {@link community}:
 * {
 *   groupMetadata: {
 *     id: {
 *       server: 'g.us',
 *       user: 'XXXXXXXXXX',
 *       _serialized: '[email protected]'
 *     },
 *     creation: 16775XXXXXX,
 *     subject: 'CommunityName',
 *     subjectTime: 16775XXXXXX,
 *     descTime: 0,
 *     restrict: false,
 *     announce: false,
 *     noFrequentlyForwarded: false,
 *     ephemeralDuration: 0,
 *     membershipApprovalMode: false,
 *     memberAddMode: 'admin_add',
 *     reportToAdminMode: false,
 *     size: 0,
 *     support: false,
 *     suspended: false,
 *     terminated: false,
 *     uniqueShortNameMap: {},
 *     isLidAddressingMode: false,
 *     isParentGroup: true,
 *     isParentGroupClosed: true,
 *     defaultSubgroup: {
 *       server: 'g.us',
 *       user: 'YYYYYYYYYY',
 *       _serialized: '[email protected]'
 *     },
 *     allowNonAdminSubGroupCreation: false,
 *     lastActivityTimestamp: 0,
 *     lastSeenActivityTimestamp: 0,
 *     incognito: false,
 *     participants: [
 *      *   {
        *     id: {
        *       server: 'c.us',
        *       user: 'ZZZZZZZZZZ',
        *       _serialized: '[email protected]'
        *     },
        *     isAdmin: true,
        *     isSuperAdmin: false
        *   },
        *   ...
 *     ],
 *     pendingParticipants: [],
 *     pastParticipants: [],
 *     membershipApprovalRequests: [],
 *     subgroupSuggestions: [],
 *     isDefaultSubgroup: false
 *   },
 *   isCommunity: true,
 *   id: {
 *     server: 'g.us',
 *     user: 'XXXXXXXXXX',
 *     _serialized: '[email protected]'
 *   },
 *   name: 'CommunityName',
 *   isGroup: true,
 *   isReadOnly: false,
 *   unreadCount: 0,
 *   timestamp: undefined,
 *   archived: undefined,
 *   pinned: false,
 *   isMuted: true,
 *   muteExpiration: -1,
 *   lastMessage: undefined
 * }
 */

2. To get the default community subgroup object (is an instance of `GroupChat`):

let subgroup;
subgroup = await client.getChatById('[email protected]');
// OR
[subgroup] = (await client.getChats()).filter(chat => chat?.groupMetadata.isDefaultSubgroup && chat.name === 'CommunityName');
/**
 * The example output of the {@link subgroup}:
 * {
 *   groupMetadata: {
 *     id: {
 *       server: 'g.us',
 *       user: 'XXXXXXXXXX',
 *       _serialized: '[email protected]'
 *     },
 *     creation: 16775XXXXX,
 *     subject: 'CommunityName',
 *     subjectTime: 16775XXXXX,
 *     descTime: 0,
 *     restrict: false,
 *     announce: true,
 *     noFrequentlyForwarded: false,
 *     ephemeralDuration: 0,
 *     membershipApprovalMode: false,
 *     memberAddMode: 'admin_add',
 *     reportToAdminMode: false,
 *     size: 2,
 *     support: false,
 *     suspended: false,
 *     terminated: false,
 *     uniqueShortNameMap: {},
 *     isLidAddressingMode: false,
 *     isParentGroup: false,
 *     isParentGroupClosed: false,
 *     parentGroup: {
 *       server: 'g.us',
 *       user: 'YYYYYYYYYY',
 *       _serialized: '[email protected]'
 *     },
 *     generalSubgroup: false,
 *     generalChatAutoAddDisabled: false,
 *     allowNonAdminSubGroupCreation: false,
 *     lastActivityTimestamp: 0,
 *     lastSeenActivityTimestamp: 0,
 *     incognito: true,
 *     participants: [ ... ],
 *     pendingParticipants: [],
 *     pastParticipants: [ ... ],
 *     membershipApprovalRequests: [],
 *     subgroupSuggestions: [],
 *     isDefaultSubgroup: true
 *   },
 *   id: {
 *     server: 'g.us',
 *     user: 'XXXXXXXXXX',
 *     _serialized: '[email protected]'
 *   },
 *   name: 'CommunityName',
 *   isGroup: true,
 *   isReadOnly: false,
 *   unreadCount: 0,
 *   timestamp: 1696XXXXX,
 *   archived: undefined,
 *   pinned: false,
 *   isMuted: false,
 *   muteExpiration: 0,
 *   lastMessage: undefined
 * }
 */

3. To create the community:

let createdCommunity;
/**
 * The example output of the {@link createdCommunity}:
* {
*   title: 'CommunityName',
*   cid: {
*     server: 'g.us',
*     user: 'ZZZZZZZZZZ',
*     _serialized: '[email protected]'
*   },
*   defaultSubgroup: {
*     server: 'g.us',
*     user: 'WWWWWWWWW',
*     _serialized: '[email protected]'
*   },
*   createdAtTs: timestamp
* }
*/
createdCommunity = await client.createCommunity('CommunityName');

// You can also provide optional parametes:
createdCommunity = await client.createCommunity('CommunityName', {
    description: 'Description',
    subGroupIds: ['[email protected]', '[email protected]', '[email protected]'], // group IDs to link to the community
    membershipApprovalMode: true, // false by default
    allowNonAdminSubGroupCreation: true // false by default
});

4. To link subgroups to the community:

const community = await client.getChatById('[email protected]');
/**
 * The example output of the method execution:
 * {
 *   linkedGroupIds: [ '[email protected]' ],
 *   failedGroups: [
 *     {
 *       groupId: '[email protected]',
 *       code: 409,
 *       message: 'SubGroupConflictError'
 *     },
 *     {
 *       groupId: '[email protected]',
 *       code: 403,
 *       message: 'SubGroupForbiddenError'
 *     }
 *   ]
 * }
 */
console.log(await community.linkSubgroups(['[email protected]', '[email protected]', '[email protected]']));

5. To unlink subgroups from the community:

const community = await client.getChatById('[email protected]');
/**
 * The example output of the unlinking result is as the linking one
 * but also you can provide an optional parameter 'removeOrphanMembers':
 */
console.log(await community.unlinkSubgroups(
    ['[email protected]', '[email protected]', '[email protected]'],
    { removeOrphanMembers: true } // false by default
));

6. To join community subgroup:

let result;

result = await client.joinSubgroup('[email protected]', '[email protected]');
// OR
const community = await client.getChatById('[email protected]');
result = await community.joinSubgroup('[email protected]');

/**
 * Example of the {@link result} object:
 * 
 * {
 *   gid: {
 *     server: 'g.us',
 *     user: 'YYYYYYYYY',
 *     _serialized: '[email protected]'
 *   },
 *   code: 200,
 *   message: 'The membership request was sent or you joined the subgroup successfully'
 * }
 */
console.log(result);

7. To promote/demote community members:

const community = await client.getChatById('[email protected]');
/**
 * The example output of the method execution (the same output structure is for the demoting):
 * [
 *   {
 *     id: {
 *       server: 'c.us',
 *       user: 'YYYYYYYYYY',
 *       _serialized: '[email protected]'
 *     },
 *     code: 403,
 *     message: "The participant can't be promoted, maybe they are not a community member"
 *   },
 *   {
 *     id: {
 *       server: 'c.us',
 *       user: 'ZZZZZZZZZZ',
 *       _serialized: '[email protected]'
 *     },
 *     code: 200,
 *     message: 'The participant was promoted successfully'
 *   }
 * ]
 */
console.log(await community.promoteParticipants(['[email protected]', '[email protected]']));

8. To remove participants:

const community = await client.getChatById('[email protected]');
/**
 * The example output of the method execution (the same output structure is for the participants adding):
 * {
 *   '[email protected]': {
 *     code: 200,
 *     message: 'The participant was removed successfully from the community and its subgroups'
 *   },
 *   '[email protected]': {
 *     code: 409,
 *     message: 'The participant is not a community member'
 *   }
 * }
 */
console.log(await community.removeParticipants(['[email protected]', '[email protected]']));

9. To get community participants:

const community = await client.getChatById('[email protected]');
/**
 * The example output of the method execution:
 * [
 *   {
 *     id: {
 *       server: 'c.us',
 *       user: 'XXXXXXXXXX',
 *       _serialized: '[email protected]'
 *     },
 *     isAdmin: false,
 *     isSuperAdmin: false
 *   },
 *   {
 *     id: {
 *       server: 'c.us',
 *       user: 'YYYYYYYYYY',
 *       _serialized: '[email protected]'
 *     },
 *     isAdmin: true,
 *     isSuperAdmin: false
 *   },
 *   ...
 * ]
 */
console.log(await community.getParticipants());

10. To get community subgroups:

const community = await client.getChatById('[email protected]');
/**
 * The example output of the method execution:
 * [
 *   {
 *     server: 'g.us',
 *     user: 'ZZZZZZZZZZ',
 *     _serialized: '[email protected]'
 *   },
 *   {
 *     server: 'g.us',
 *     user: 'YYYYYYYYYY',
 *     _serialized: '[email protected]'
 *   },
 *   ...
 * ]
 */
console.log(await community.getSubgroups());

11. To get joined subgroups:

const community = await client.getChatById('[email protected]');
/** The example output is the same as in getSubgroups */
console.log(await community.getJoinedSubgroups());

12. To get unjoined subgroups:

const community = await client.getChatById('[email protected]');
/** The example output is the same as in getSubgroups */
console.log(await community.getUnjoinedSubgroups());

13. To set who can add groups to the community (only admins or all members):

const community = await client.getChatById('[email protected]');
await community.setNonAdminSubGroupCreation(true); // all members can add groups to that community
await community.setNonAdminSubGroupCreation(false); // only admins can add groups to that community

14. To deactivate the community:

await client.deactivateCommunity('[email protected]');
// OR
const community = await client.getChatById('[email protected]');
await community.deactivate();

15. To leave the community:

const community = await client.getChatById('[email protected]'/* '[email protected]' */);
await community.leave();

To test this PR by yourself you can run one of the following commands:

NPM

npm install github:alechkos/whatsapp-web.js#community

YARN

yarn add github:alechkos/whatsapp-web.js#community

If you encounter any errors while testing this PR, please provide in a comment:

The code you've used without any sensitive information (use syntax highlighting for more readability)
The error you got
The library version
The WWeb version: console.log(await client.getWWebVersion());
The browser (Chrome/Chromium)

Important

You have to reapply the PR each time it is changed (new commits were pushed since your last application)

How Has The PR Been Tested (latest test on 30.11.2023)

Tested with the code provided in usage example.

Tested On:

Types of accounts:

Personal
Buisness

Environment:

Android 10:
- WhatsApp: latest
- WA Business: latest
Windows 10:
- WWebJS: v1.23.1-alpha.0
- WWeb: v2.2347.56
- Puppeteer: v18.2.1
- Node: v18.17.1
- Chrome: latest

Types of Changes

Dependency change
Bug fix (non-breaking change which fixes an issue)
New feature (non-breaking change which adds functionality)
Breaking change (fix/feature that would cause existing functionality to change)

Checklist

My code follows the code style of this project
I have updated the usage example accordingly (example.js)
I have updated the documentation accordingly (index.d.ts)

joweste · 2024-02-01T19:43:06Z

@joweste

How to query the ProfilePicUrl, membershipApprovalMode and allowNonAdminSubGroupCreation of a community by id?

What do you mean "to query"? Go through the description

Never mind. These values settings are in groupMetadata.

alechkos · 2024-02-01T19:43:48Z

@joweste

About the getParticipants problem? Is it the same problem, because I am not a community member?

In order to get community members you have at least to be its member, as mentioned here

joweste · 2024-02-01T19:54:05Z

@joweste

About the getParticipants problem? Is it the same problem, because I am not a community member?

In order to get community members you have at least to be its member, as mentioned here

Sorry, but the community admin just said me, if I am member at least one group of the community, then I am already member of the community. Does it make sense? If yes, then I should have rights to see all groups of that community and getParticipants. As I said before, I am member in 3 groups in that community

alechkos · 2024-02-01T19:59:42Z

@joweste

Sorry, but the community admin just said me, if I am member at least one group of the community, then I am already member of the community.

You are right, my fault.
I have to check the Community.getParticipants method, could be that sonething is broke in the latest wweb versions

joweste · 2024-02-01T20:01:32Z

@joweste

Sorry, but the community admin just said me, if I am member at least one group of the community, then I am already member of the community.

You are right, my fault. I have to check the Community.getParticipants method, could be that sonething is broke in the latest wweb versions

Thank you. Could you see why I can´t list all groups in the community where I am member as well?

joweste · 2024-02-02T22:58:34Z

Hi,
How can I get the profilePictureUrl of the community?
I have tried to use the community.id._serialized as:

try {
        profilePicUrl = await client.getProfilePicUrl(community.id._serialized);
} catch (error) {
        console.log(error)
        profilePicUrl = "";
}

I also tried to get the picture using the "defaultSubgroup._serialized" from groupMetadata but no look.

joweste · 2024-02-03T00:28:07Z

Only as information, if I get the my commonGroups with the community admin user, it shows 10 groups.
For sample:
if 'nn' is the serialized id of the admin communnity user, and I do:

const contact = await client.getContactById(nn);
const commomGroups = await contact.getCommonGroups();

It reports all 10 groups of the community.

But if get the subgroups of the community as:

const community = await client.getChatById('[email protected]');
console.log(await community.getSubgroups());

it reports only 4 groups( where 3 are joined and 1 unjoined)

joweste · 2024-02-03T14:32:12Z

Hi, when I get the subgroups participants of a community, I get many @lid numbers.

For sample:

const groupChat = await client.getChatById(subgroup community id);
const participants = await groupChat.groupMetadata.participants;

Here, 'participants' has many @lid numbers.

Is possible I get the contact names of this @lid numbers?

alechkos · 2024-02-03T16:34:32Z

@joweste

Hi, when I get the subgroups participants of a community, I get many @lid numbers.

#2330 (comment)

joweste · 2024-02-03T18:27:08Z

Please, What's difference between join a group and link a group to community?

alechkos · 2024-02-03T18:37:57Z

@joweste

Please, What's difference between join a group and link a group to community?

With joinSubgroup you as a user can become a member of one of the community subgroups (similar to acceptInvite or acceptGroupV4Invite),
with linkSubgroups you as a community admin can link to that community (add) more subgroups

joweste · 2024-02-03T18:51:36Z

With joinSubgroup you as a user can become a member of one of the community subgroups (similar to acceptInvite)

Hi, But in your sample, you are joining a group to community, not a user. Is this ok?

const community = await client.getChatById('[email protected]');
result = await community.joinSubgroup('[email protected]');

alechkos · 2024-02-03T18:54:34Z

@joweste

Hi, But in your sample, you are joining a group to community, not a user. Is this ok?

In the sample I am not joining a group to community, but the current user (a bot) joins the subgroup of a community

joweste · 2024-02-03T19:03:45Z

@joweste

Hi, But in your sample, you are joining a group to community, not a user. Is this ok?

In the sample I am not joining a group to community, but the current user (a bot) joins the subgroup of a community

I got it. Thanks.
This syntax is more clear to me:

/** Joins a community subgroup by community ID and a subgroup ID */
 joinSubgroup: (communityId: string, subGroupId: string) => Promise<JoinGroupResponse>;

joweste · 2024-02-04T21:47:28Z

Hi, does a specific subgroup can be linked to many communities?

saumilsdk · 2024-02-12T16:19:02Z

Really required feature!! Please approve and merge :)

joweste · 2024-02-24T23:28:35Z

@joweste

Sorry, but the community admin just said me, if I am member at least one group of the community, then I am already member of the community.

You are right, my fault. I have to check the Community.getParticipants method, could be that sonething is broke in the latest wweb versions

Hi, is there some news about it? Sorry to ask you.

reddyram · 2024-03-24T17:20:48Z

Does group_join and group_ leave with communities as well?
I mean do they get triggered when user leaves or joins a community?

alechkos added 15 commits August 24, 2023 05:04

leave method is now compatible with community

76b7595

added setNonAdminSubGroupCreation

b900024

docs updated

2c47406

added usage example

ae2bf17

leave method fixed

a4482b4

small update to improve the performance of findImpl fix

085c773

window.compareWwebVersions fixed

2ac0ac4

added defaultSubgroupId to groupMetadata

bf6b9b5

ChatFactory extended to create a Community

e802746

added getSubgroups

725904f

Merge branch 'main' into community

c5e20c8

added isCommunity property

8afbeae

usage example fixed

2ad217d

added createCommunity method

1f8f834

error to be returned as number

1c18fe0

Epale10 approved these changes Sep 24, 2023

View reviewed changes

alechkos added 4 commits September 25, 2023 03:07

default error message was missing

90f5a75

separate logic of linking subgroups

06681f3

jsdocs fixed

96b12f8

added linkSubgroups method

6177438

alechkos force-pushed the community branch from 20b44dd to 6177438 Compare September 27, 2023 02:21

added unlinkSubgroups method

1842db0

alechkos force-pushed the community branch 2 times, most recently from 47a16fa to 2bef97e Compare September 29, 2023 00:51

alechkos added 2 commits September 29, 2023 18:26

fixed getting community

d6381aa

added deactivateCommunity method

07a4b29

alechkos force-pushed the community branch 2 times, most recently from a6a547b to e5e15ea Compare September 30, 2023 13:36

alechkos added 2 commits October 1, 2023 15:37

added removeParticipants method for the community

5c75a10

fixed Community instance creation

262a30c

Merge branch 'main' into community

38d151d

Merge branch 'main' into community

a66a4cc

alechkos marked this pull request as draft April 16, 2024 02:52

Repository owner locked and limited conversation to collaborators Apr 16, 2024

Repository owner unlocked this conversation Apr 19, 2024

alechkos added 7 commits April 22, 2024 15:27

Merge branch 'main' into community

2469853

style: fix broken link in readme file

eb8e12c

Merge branch 'main' into community

9b68769

Merge branch 'main' into community

906771b

Merge branch 'main' into community

8b59a54

Merge branch 'main' into community

c1b3eed

Merge branch 'main' into community

76b031c

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat: `Community` #2531

feat: `Community` #2531

alechkos commented Sep 23, 2023 •

edited

joweste commented Feb 1, 2024

alechkos commented Feb 1, 2024 •

edited

joweste commented Feb 1, 2024 •

edited

alechkos commented Feb 1, 2024

joweste commented Feb 1, 2024

joweste commented Feb 2, 2024

joweste commented Feb 3, 2024 •

edited

joweste commented Feb 3, 2024 •

edited by alechkos

alechkos commented Feb 3, 2024 •

edited

joweste commented Feb 3, 2024

alechkos commented Feb 3, 2024

joweste commented Feb 3, 2024

alechkos commented Feb 3, 2024

joweste commented Feb 3, 2024

joweste commented Feb 4, 2024

saumilsdk commented Feb 12, 2024

joweste commented Feb 24, 2024

reddyram commented Mar 24, 2024

feat: Community #2531

Are you sure you want to change the base?

feat: Community #2531

Conversation

alechkos commented Sep 23, 2023 • edited

Table of Contents

- Description

- Related Issues

- Usage Example

- I Want to Test this PR

- I Got an Error While Testing This PR ❌

- How Has the PR Been Tested (latest test on 30.11.2023)

- Types of Changes

Description

Related Issues

Usage Example

1. To get the community object (the parent group, is an instance of Community):

2. To get the default community subgroup object (is an instance of GroupChat):

3. To create the community:

4. To link subgroups to the community:

5. To unlink subgroups from the community:

6. To join community subgroup:

7. To promote/demote community members:

8. To remove participants:

9. To get community participants:

10. To get community subgroups:

11. To get joined subgroups:

12. To get unjoined subgroups:

13. To set who can add groups to the community (only admins or all members):

14. To deactivate the community:

15. To leave the community:

To test this PR by yourself you can run one of the following commands:

If you encounter any errors while testing this PR, please provide in a comment:

How Has The PR Been Tested (latest test on 30.11.2023)

Tested On:

Types of accounts:

Environment:

Types of Changes

Checklist

joweste commented Feb 1, 2024

alechkos commented Feb 1, 2024 • edited

joweste commented Feb 1, 2024 • edited

alechkos commented Feb 1, 2024

joweste commented Feb 1, 2024

joweste commented Feb 2, 2024

joweste commented Feb 3, 2024 • edited

joweste commented Feb 3, 2024 • edited by alechkos

alechkos commented Feb 3, 2024 • edited

joweste commented Feb 3, 2024

alechkos commented Feb 3, 2024

joweste commented Feb 3, 2024

alechkos commented Feb 3, 2024

joweste commented Feb 3, 2024

joweste commented Feb 4, 2024

saumilsdk commented Feb 12, 2024

joweste commented Feb 24, 2024

reddyram commented Mar 24, 2024

feat: `Community` #2531

feat: `Community` #2531

alechkos commented Sep 23, 2023 •

edited

1. To get the community object (the parent group, is an instance of `Community`):

2. To get the default community subgroup object (is an instance of `GroupChat`):

alechkos commented Feb 1, 2024 •

edited

joweste commented Feb 1, 2024 •

edited

joweste commented Feb 3, 2024 •

edited

joweste commented Feb 3, 2024 •

edited by alechkos

alechkos commented Feb 3, 2024 •

edited