feat: group mentions + improved user mentions

[alechkos]

Table of Contents

- Description

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

• The environment the PR was tested on

- Types of Changes

---

Description

This PR introduces logic for mentioning groups in messages and improves the logic for mentioning users:

1. Group mentions:
   • Added option to send a message with clickable group mentions, and when the group mention is clicked, a chat with the mentioned group will be opened.

     NOTE:
     The user that does not participate in the mentioned group,
     will not be able to open that mentioned group,
     the same if the group does not exist

   • Added Message.getGroupMentions method to get an array of GroupChat objects from a message with group mentions
2. User mentions:
   • Added logic for mentioning those users with whom you have never interacted
   • Added a check to verify the existence of the user, preventing accidental mentions of unregistered phone numbers on WhatsApp

---

Usage Example

client.on('message', async (msg) => {
    const chat = await msg.getChat();
    const userNumber = '26022602XX';

    if (msg.body === '!mentionUsers') {
        /**
         * To mention one user you can pass user's ID to 'mentions' property as is,
         * without wrapping it in Array, and a user's phone number to the message body:
         */
        await chat.sendMessage(`Hi @${userNumber}`, {
            mentions: userNumber + '@c.us'
        });

        // To mention a list of users:
        await chat.sendMessage(`Hi @${userNumber}, @${userNumber}`, {
            mentions: [userNumber + '@c.us', userNumber + '@c.us']
        });
    }
    
    if (msg.body === '!mentionGroups') {
        const chat = await msg.getChat();
        const groupId = 'YYYYYYYYYY@g.us';
        /**
         * Sends clickable group mentions, the same as user mentions.
         * When the mentions are clicked, it opens a chat with the mentioned group.
         * The 'groupMentions.subject' can be custom
         * 
         * @note The user that does not participate in the mentioned group,
         * will not be able to click on that mentioned group, the same if the group does not exist
         *
         * To mention one group:
         */
        await chat.sendMessage(`Check the last message here: @${groupId}`, {
            groupMentions: { subject: 'GroupSubject', id: groupId }
        });

        // To mention a list of groups:
        await chat.sendMessage(`Check the last message in these groups: @${groupId}, @${groupId}`, {
            groupMentions: [
                { subject: 'FirstGroup', id: groupId },
                { subject: 'SecondGroup', id: groupId }
            ]
        });
    }

    if (msg.body === '!getGroupMentions') {
        // To get group mentions from a message:
        const groupId = 'ZZZZZZZZZZ@g.us';
        const msg = await client.sendMessage('chatId', `Check the last message here: @${groupId}`, {
            groupMentions: { subject: 'GroupSubject', id: groupId }
        });

        /** {@link groupMentions} is an array of `GroupChat` */
        const groupMentions = await msg.getGroupMentions();
    }
});

---

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

• NPM

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

• YARN

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

---

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

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.2353.0
  • 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)

[crash-overdrive]

Using TypeScript, I can't use groupMentions as a MessageSendOption while calling the function client.SendMessage. Line 802-817 in Client.js should contain property groupMentions to fix this (I think). @alechkos

[alechkos]

@crash-overdrive

Line 802-817 in Client.js should contain property groupMentions to fix this

You are right, I forgot to add this
Will be fixed

[crash-overdrive]

@crash-overdrive

Line 802-817 in Client.js should contain property groupMentions to fix this

You are right, I forgot to add this Will be fixed

Lemme know when you plan on fixing this! Using it for a project of mine :D

[alechkos]

@crash-overdrive
Fixed, let me know if there are another issues

[shavy4452]

is this ready for merge? I am waiting for this to include in my project.

[alechkos]

@shavy4452

is this ready for merge?

Yes it is

[shirser121]

LGTM