feat: new chat/group settings + methods + minor updates

[alechkos]

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 01.11.2023)

• The environment the PR was tested on

- Types of Changes

---

Description

1. Added new chat and group settings:

   • Chat.setMessageExpiration - sets the Message Expiration Timer for a chat or a group. Valid values for passing to the method are:
     • 0 for message expiration removal
     • 1 for 24 hours message expiration
     • 2 for 7 days message expiration
     • 3 for 90 days message expiration

       IMPORTANT:
       Any other value passed to the method will result in an error

   • GroupChat.setMembershipApprovalMode - sets the Membership Approval Mode in a group. When turned on, group admins will be required to approve anyone who wishes to join the group

     IMPORTANT:
     If the mode was turned off, all pending requests to join the group will be automatically approved

   • GroupChat.setReportToAdminMode - sets the Report To Admin Mode. When turned on, every group participant could report every message sent in the group, these reports will be sent to group admins for review. Group admins could see those reports in Sent for admin review section in the group and make manipulations with those messages
   • GroupChat.setGroupMemberAddMode – sets who can add others to the group: either only admins or all the group members. If turned on, only the group admins can add others to the group

2. Added new methods:

   • Message.sendForAdminReview allows sending any group message to group admins for a review (to report that message to admins)

     NOTE:
     The method will work only if 'Report To Admin Mode' is turned on

   • GroupChat.getReportedMessages – gets the reported to group admins messages sent in that group

     NOTE:
     The method will work only if 'Report To Admin Mode' is turned on
     and a current user is a group admin

   • Chat.hasKeptMessages - indicates if there are kept messages in that chat
   • Chat.getKeptMessages - gets kept messages from that chat
   • Message.keepMessage and Message.unkeepMessage - methods for keeping/unkeeping messages in a chat

     NOTE:
     These two methods will work only if message expiration timer is turned on for the chat

3. Events:

   • Added message_kept_unkept event that is emitted when message was kept or unkept
   • Fixed group_join event: added a case when a user joins the group after the admin approval
   • Fixed group_leave event: is now emitted also when a current user leaves a group or a community
   • Fixed group_admin_changed event: is now emitted when any group member is promoted or demoted (not only the current user as before)

4. Other changes:

   • groupMetadata extended with properties:
     • iAmMember - indicates if a current user is a member in the group
     • iAmAdmin - indicates if a current user is an admin in the group
     • iAmSuperAdmin - indicates if a current user is an admin who created the group

       NOTE:
       If you, being a superadmin in a group, leave it, you will lose the status of superadmin forever, even if another admin promotes you as an admin after rejoining this group.
       If the superadmin leaves the group, this group will remain without the superadmin forever.

     • ephemeralDuration - the duration (in seconds) in which messages will disappear in chat (if the corresponding setting is enabled)
   • Other minor updates

---

Related Issues

The PR closes #2441, closes #1559

---

Usage Example

1. To set the message expiration timer:

client.on('message', async (msg) => {
    if (msg.body === '!msgTimer') {
        const chat = await client.getChatById('number@c.us');
        // OR
        const group = await client.getChatById('groupId@g.us');
        /**
         * Valid values for passing to the method are:
         * 0 for message expiration removal,
         * 1 for 24 hours message expiration,
         * 2 for 7 days message expiration,
         * 3 for 90 days message expiration
         */
        /** For 24 hours message expiration: */
        await chat.setMessageExpiration(1);
        /** For 90 days message expiration: */
        await group.setMessageExpiration(3);
    }
});

2. To set the Membership Approval Mode:

client.on('message', async (msg) => {
    if (msg.body === '!membershipApprovalMode') {
        const group = await client.getChatById('groupId@g.us');
        if (group.isGroup) {
            /** Turns the 'Membership Approval Mode' on: */
            await group.setMembershipApprovalMode(/* true */);
            /**
             * Turns the 'Membership Approval Mode' off
             * Note: if the mode is turned off, all pending requests to join the group will be approved
             */
            await group.setMembershipApprovalMode(false);
        }
    }
});

3. To set the Report To Admin Mode:

client.on('message', async (msg) => {
    if (msg.body === '!reportToAdminMode') {
        const group = await client.getChatById('groupId@g.us');
        if (group.isGroup) {
            /** Turns the 'Report To Admin Mode' on: */
            await group.setReportToAdminMode(/** true */);
            /** Turns the 'Report To Admin Mode' off: */
            await group.setReportToAdminMode(false);
        }
    }
});

4. To set the Group Member Add Mode:

client.on('message', async (msg) => {
    if (msg.body === '!groupMemberAddMode') {
        const group = await client.getChatById('groupId@g.us');
        if (group.isGroup) {
            /**
             * Turns the 'Group Member Add Mode' on.
             * If turned on, only group admins can add others to that group
             */
            await group.setGroupMemberAddMode(/* true */);
            /**
             * Turns the 'Group Member Add Mode' off
             * If turned off, all participants can add others to this group
             */
            await group.setGroupMemberAddMode(false);
        }
    }
});

5. To send a message for a group admin review:

client.on('message', async (msg) => {
    /** True if the operation completed successfully, false otherwise */
    console.log(await msg.sendForAdminReview());
});

6. To get reported to group admin messages sent in that group:

client.on('message', async (msg) => {
    if (msg.body === '!getReportedMsgs') {
        const group = await msg.getChat();
        if (group.isGroup) {
            const reportedMsgs = await group.getReportedMessages();
        }

        // You can also call that method on `Client` object:
        const reportedMsgs = await client.getReportedMessages('groupId@g.us');

        /**
         * The example of the resulting structure of {@link reportedMsgs}:
         * [
         *   {
         *     reporters: [
         *       {
         *         reporterId: {
         *           server: 'c.us',
         *           user: 'XXXXXXXXXX',
         *           _serialized: 'XXXXXXXXXX@c.us'
         *         },
         *         reportedAt: 1645XXXXXX
         *       },
         *       ...
         *     ],
         *     message: Message {...}
         *   },
         *   ...
         * ]
         */
        console.log(reportedMsgs);
    }
});

7. To check if a chat or a group has kept messages:

client.on('message', async (msg) => {
    if (msg.body === '!hasKeptMsgs') {
        const chat = await msg.getChat();
        const hasKeptMsgs = await chat.hasKeptMessages();

        // You can also call that method on `Client` object:
        const hasKeptMsgs = await client.hasKeptMessages('number@c.us'/* 'groupId@g.us' */);

        /** True if there are kept messages in a chat or a group, false otherwise */
        console.log(hasKeptMsgs);
    }
});

8. To get kept messages from a chat or a group:

client.on('message', async (msg) => {
    if (msg.body === '!getKeptMsgs') {
        const chat = await msg.getChat();
        const keptMsgs = await chat.getKeptMessages();

        // You can also call that method on `Client` object:
        const keptMsgs = await client.getKeptMessages('number@c.us'/* 'groupId@g.us' */);

        /** An array of `Message` objects */
        console.log(keptMsgs);
    }
});

9. To keep or unkeep a message:

client.on('message', async (msg) => {
    /** If you want to keep that message: */
    const ifKept = await msg.keepMessage();
    /** True if the operation completed successfully, false otherwise */
    console.log(ifKept);

    /** In order to unkeep that message: */
    await msg.unkeepMessage();
});

10. To listen to message status, whether was kept or unkept:

client.on('message_kept_unkept', (msg, status) => {
    /** The message that was affected */
    console.log(msg);
    /** The message status: whether was kept or unkept */
    console.log(status);
});

---

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

• NPM

npm install github:alechkos/whatsapp-web.js#chat-group-props

• YARN

yarn add github:alechkos/whatsapp-web.js#chat-group-props

---

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

1. The code you've used without any sensitive information (use syntax highlighting for more readability)
2. The error you got
3. The library version
4. The WWeb version: console.log(await client.getWWebVersion());
5. 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 01.11.2023)

The PR was tested with a 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 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)

[matheus-de-araujo]

Very document code, congratulations

[Halphas]

Did this also fix set group description and set group profile pic? If not, I can provide it if u like.