feat: forward messages with caption text

[alechkos]

[!IMPORTANT] https://github.com/pedroslopez/whatsapp-web.js/labels/breaking%20change

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

• The environment the PR was tested on

- Types of Changes

---

Description

The PR introduces functionality that allows to forward media and attachment messages with their captions, along with the ability to disable the Forwarded tag above a forwarded message.

❗ Breaking Changes:

• Now media and attachment messages are forwarded with their captions by default
• The method returns a boolean value that indicates the success of forwarding the message

You can forward a message without a caption by setting an optional property withCaption to false within Message.forward method. Also you can turn off the Forwarded tag above a fowarded message by setting an optional property displayAsForwarded to false.

---

Related Issues

The PR closes #1650, closes #2426, closes #2435, closes #2629

---

Usage Example

client.on('message', async (message) => {
    if (message.author) {
        /**
         * Let's say the message was sent in a group
         * and you want to forward it to its author:
         */

        // 1. By default the message will be forwarded with a caption (if provided):
        await message.forward(message.author);

        // 2. To forward without a caption text, use { withCaption: false }:
        await message.forward(message.author, { withCaption: false });

        // 3. To forward without a 'Forwarded' title, use { displayAsForwarded: false }:
        await message.forward(message.author, { displayAsForwarded: false });
    }
});

---

To test this PR by yourself you should do two steps:

1. Install the PR by running one of the following commands:

• NPM

npm install github:alechkos/whatsapp-web.js#forward-with-caption

• YARN

yarn add github:alechkos/whatsapp-web.js#forward-with-caption

2. Lock your WWeb version on 2.2412.54:

const wwebVersion = '2.2412.54';

const client = new Client({
    authStrategy: new LocalAuth(), // your authstrategy here
    puppeteer: {
        // puppeteer args here
    },
    // locking the wweb version
    webVersionCache: {
        type: 'remote',
        remotePath: `https://raw.githubusercontent.com/wppconnect-team/wa-version/main/html/${wwebVersion}.html`,
    },
});

---

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

The functionality has been tested by sending different types of messages:

• regular text messages
• view once messages (are forwarded also)
• messages with link preview
• messages with mentions
• media messages (photo/video/gif/sticker/animated sticker/audio/voice)
• attachment messages (document)
• messages with contact card/s
• polls

Tested On:

Types of accounts:

• Personal
• Buisness

Environment:

• Android 10:
  • WhatsApp: latest
  • WA Business: latest
• Windows 10:
  • WWebJS: 1.23.1-alpha.6
  • WWeb: v2.2412.54
  • Puppeteer: v18.2.1
  • Node: v18.17.1
  • Chrome: latest

---

Types of Changes

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

Checklist

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

[tuyuribr]

I think if we change the default we should warn users about this before changing the default option. How would we inform them?

[alechkos]

I think if we change the default we should warn users about this before changing the default option. How would we inform them?

Yes i was considering keeping the old functionality as the default, but then Pedro pointed out that forwarding messages with a caption is the default functionality provided by wweb themselves, and it seemed appropriate to me to have message forwarding work the same way for us too. In any case i mentioned in the documentation and usage example that the default functionality has been changed. Please let me know if you think something more needs to be done.

[tuyuribr]

I think if we change the default we should warn users about this before changing the default option. How would we inform them?

Yes i was considering keeping the old functionality as the default, but then Pedro pointed out that forwarding messages with a caption is the default functionality provided by wweb themselves, and it seemed appropriate to me to have message forwarding work the same way for us too. In any case i mentioned in the documentation and usage example that the default functionality has been changed. Please let me know if you think something more needs to be done.

Excellent work alechkos, I think when we merge this to the main branch we should inform users in discord.

[shirser121]

Can we return the new message object after the sending?

[alechkos]

@shirser121

Can we return the new message object after the sending?

I think it can be done, i will check later it requires some work

[jrocha]

just tested and it is working. didn't try new options. I was getting the error below:

Error: Evaluation failed: TypeError: chat.forwardMessages is not a function at puppeteer_evaluation_script:5:31 at ExecutionContext._evaluateInternal (/opt/blue/node_modules/whatsapp-web.js/node_modules/puppeteer/lib/cjs/puppeteer/common/ExecutionContext.js:221:19) at process.processTicksAndRejections (node:internal/process/task_queues:95:5) at async ExecutionContext.evaluate (/opt/blue/node_modules/whatsapp-web.js/node_modules/puppeteer/lib/cjs/puppeteer/common/ExecutionContext.js:110:16) at async Message.forward (/opt/blue/node_modules/whatsapp-web.js/src/structures/Message.js:401:9)

[jrocha]

what is holding this branch from being merged ?

[jrocha]

@pedroslopez @alechkos how can I help to get this merged?

[alechkos]

@jrocha

Fixed

[KINGMASTERAPP]

Where do I put the person's number?

[alechkos]

@KINGMASTERAPP

Where do I put the person's number?

// ...
client.on('message', async (message) => {
    const personsNumber = '[email protected]';
    await message.forward(personsNumber);
});
// ...

[KINGMASTERAPP]

Sorry to bother you, but how do you set it up for me to use api? like this

app.post('/forwards', (req, res) => { const messageId = req.body.messageId; const chatId = req.body.chatId; const destinationChatId = req.body.destinationChatId;

const sender = req.body.sender;

const client = sessions.find(sess => sess.id == sender)?.client;

if (!client) { return res.status(422).json({ status: false, message: The sender: ${sender} is not found! }); }

const message = _getMessageById(client, messageId, chatId)

client.message.forward(destinationChatId).then(response => { res.status(200).json({ status: true, response: response }); }).catch(err => { res.status(500).json({ status: false, response: err }); }); });

[jrocha]

Just tested!

regular text messages messages with mentions media messages (audio/voice)

Tested On

Types of accounts:

Personal accounts

Environment

Android 10 WhatsApp: latest Ubuntu: 20.04 WWeb: = 2.2353.56 Puppeteer: v19.4.1 Node: v18.17.1 Chrome: latest

Waiting for this merge

[Matheus-Lima-Moreira]

it works fine to me

[jrocha]

Hey @pedroslopez @aliyss @tuyuribr @shirser121, this PR has been pending for a while. Can we discuss how to get it merged?

[alechkos]

@tuyuribr

We need to inform people of this (That the default now is fowarding with caption)

Sure, we can do it in our Discord channel

[jrocha]

I've been working on this for several months now, and I'm currently awaiting the integration of this branch into the main branch. Is there any way I can assist or contribute to expedite this process?

[Matheus-Lima-Moreira]

I'm facing a problem recently, when forwarding images the "message_create" event is being fired but without the image and next to this event the "message_edit" event is fired giving an error in my application

[JuniorRibas]

Why didn't you merge with master? @pedroslopez

[alechkos]

@PurpShell

you sure there is no built-in web function that can simplify window.WWebJS.forwardMessage?

We have forwardMessagesToChats in 450192 module in WWeb v2.2412.54, but with the use of this built-in function we can't return true/false that will indicate the success of forwarding the message, also we won't be able to turn off the Forwarded tag on the forwarded message

[purpshell]

@PurpShell

you sure there is no built-in web function that can simplify window.WWebJS.forwardMessage?

We have forwardMessagesToChats in 450192 module in WWeb v2.2412.54, but with the use of this built-in function we can't return true/false that will indicate the success of forwarding the message, also we won't be able to turn off the Forwarded tag on the forwarded message

I'm sure there must be an easier fix, and "turning off" the forwarded tag is unnecessary

[alechkos]

I'm sure there must be an easier fix, and "turning off" the forwarded tag is unnecessary

Use forwardMessagesToChats then. Easier than this? 😄

[purpshell]

I'm sure there must be an easier fix, and "turning off" the forwarded tag is unnecessary

Use forwardMessagesToChats then. Easier than this? 😄

yeah you can reimplement in that. You can try-catch it to see if there were errors during transit ig