feat(chat): add markMessageAsPlayed endpoint (audio receipt) (#2519)

Adds POST /chat/markMessageAsPlayed/{instance} for marking received audio
messages as played (blue microphone in WhatsApp), mirroring the existing
markMessageAsRead pattern.

Baileys natively supports sock.sendReceipts(keys, 'played') but Evolution
only exposed the 'read' type via /chat/markMessageAsRead. CRMs that play
back voice notes received from contacts had no way to send the played
ack — this endpoint fills the gap with the same DTO/schema shape (key
shape: id, fromMe, remoteJid) under a 'playedMessages' array.

Mirrors:
- DTO: MarkMessageAsPlayedDto extends Key array (mirrors ReadMessageDto)
- Schema: markMessageAsPlayedSchema (JSONSchema7, mirrors readMessageSchema)
- Service: markMessageAsPlayed -> client.sendReceipts(keys, 'played')
- Controller: markMessageAsPlayed -> waMonitor delegation
- Router: POST routerPath('markMessageAsPlayed')

Use case: agent CRMs (Chatwoot-like) that present audio messages with a
play button and need to send the played receipt back to the contact when
the agent plays the audio in the dashboard.

Author: rafavasconcelost

src/api/controllers/chat.controller.ts

@@ -5,6 +5,7 @@ import {
   DeleteMessage,
   getBase64FromMediaMessageDto,
   MarkChatUnreadDto,
+  MarkMessageAsPlayedDto,
   NumberDto,
   PrivacySettingDto,
   ProfileNameDto,
@@ -31,6 +32,10 @@ export class ChatController {
     return await this.waMonitor.waInstances[instanceName].markMessageAsRead(data);
   }
 
+  public async markMessageAsPlayed({ instanceName }: InstanceDto, data: MarkMessageAsPlayedDto) {
+    return await this.waMonitor.waInstances[instanceName].markMessageAsPlayed(data);
+  }
+
   public async archiveChat({ instanceName }: InstanceDto, data: ArchiveChatDto) {
     return await this.waMonitor.waInstances[instanceName].archiveChat(data);
   }

src/api/dto/chat.dto.ts

@@ -70,6 +70,10 @@ export class ReadMessageDto {
   readMessages: Key[];
 }
 
+export class MarkMessageAsPlayedDto {
+  playedMessages: Key[];
+}
+
 export class LastMessage {
   key: Key;
   messageTimestamp?: number;

src/api/integrations/channel/whatsapp/whatsapp.baileys.service.ts

@@ -7,6 +7,7 @@ import {
   getBase64FromMediaMessageDto,
   LastMessage,
   MarkChatUnreadDto,
+  MarkMessageAsPlayedDto,
   NumberBusiness,
   OnWhatsAppDto,
   PrivacySettingDto,
@@ -4158,6 +4159,24 @@ export class BaileysStartupService extends ChannelStartupService {
     }
   }
 
+  public async markMessageAsPlayed(data: MarkMessageAsPlayedDto) {
+    try {
+      const keys: proto.IMessageKey[] = [];
+      data.playedMessages.forEach((played) => {
+        if (isJidGroup(played.remoteJid) || isPnUser(played.remoteJid)) {
+          keys.push({ remoteJid: played.remoteJid, fromMe: played.fromMe, id: played.id });
+        }
+      });
+      // Baileys exposes sendReceipts(keys, type) where type='played' triggers the
+      // PLAYED ack (blue microphone). Used when an agent plays back an audio
+      // message received from a contact, mirroring the contact's view in WhatsApp.
+      await this.client.sendReceipts(keys, 'played');
+      return { message: 'Played messages', played: 'success' };
+    } catch (error) {
+      throw new InternalServerErrorException('Mark messages as played fail', error.toString());
+    }
+  }
+
   public async getLastMessage(number: string) {
     const where: any = { key: { path: ['remoteJid'], equals: number }, instanceId: this.instanceId };
 

src/api/routes/chat.router.ts

@@ -6,6 +6,7 @@ import {
   DeleteMessage,
   getBase64FromMediaMessageDto,
   MarkChatUnreadDto,
+  MarkMessageAsPlayedDto,
   NumberDto,
   PrivacySettingDto,
   ProfileNameDto,
@@ -27,6 +28,7 @@ import {
   decryptPollVoteSchema,
   deleteMessageSchema,
   markChatUnreadSchema,
+  markMessageAsPlayedSchema,
   messageUpSchema,
   messageValidateSchema,
   presenceSchema,
@@ -72,6 +74,16 @@ export class ChatRouter extends RouterBroker {
 
         return res.status(HttpStatus.CREATED).json(response);
       })
+      .post(this.routerPath('markMessageAsPlayed'), ...guards, async (req, res) => {
+        const response = await this.dataValidate<MarkMessageAsPlayedDto>({
+          request: req,
+          schema: markMessageAsPlayedSchema,
+          ClassRef: MarkMessageAsPlayedDto,
+          execute: (instance, data) => chatController.markMessageAsPlayed(instance, data),
+        });
+
+        return res.status(HttpStatus.CREATED).json(response);
+      })
       .post(this.routerPath('archiveChat'), ...guards, async (req, res) => {
         const response = await this.dataValidate<ArchiveChatDto>({
           request: req,

src/validate/chat.schema.ts

@@ -63,6 +63,28 @@ export const readMessageSchema: JSONSchema7 = {
   required: ['readMessages'],
 };
 
+export const markMessageAsPlayedSchema: JSONSchema7 = {
+  $id: v4(),
+  type: 'object',
+  properties: {
+    playedMessages: {
+      type: 'array',
+      minItems: 1,
+      uniqueItems: true,
+      items: {
+        properties: {
+          id: { type: 'string' },
+          fromMe: { type: 'boolean', enum: [true, false] },
+          remoteJid: { type: 'string' },
+        },
+        required: ['id', 'fromMe', 'remoteJid'],
+        ...isNotEmpty('id', 'remoteJid'),
+      },
+    },
+  },
+  required: ['playedMessages'],
+};
+
 export const archiveChatSchema: JSONSchema7 = {
   $id: v4(),
   type: 'object',