Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

48.6 KB
Raw Blame
import { Injectable, BadRequestException, Optional } from '@nestjs/common';
import { ConfigService } from '@nestjs/config';
import { markEngineSendFailure } from '../../common/errors/engine-send-failure';
import { mergeSentMetadata, updateMessageMetadata } from './message-metadata';
import { InjectRepository } from '@nestjs/typeorm';
import { In, Repository, QueryDeepPartialEntity } from 'typeorm';
import { SessionService } from '../session/session.service';
import { MessageProjector } from '../session/message-projector.service';
import { EngineRegistry } from '../../engine/engine-registry.service';
import { SendTextMessageDto, SendMediaMessageDto, SendAudioMessageDto, MessageResponseDto } from './dto';
import { SendTemplateMessageDto } from './dto/send-template.dto';
import { resolveMediaBody } from './media-cap.util';
import { MediaInput, IWhatsAppEngine, MessageResult } from '../../engine/interfaces/whatsapp-engine.interface';
import { Message, MessageDirection, MessageStatus } from './entities/message.entity';
import { HookManager, applySendingGate } from '../../core/hooks';
import { SendPacingService, SettleAdmission, countsTowardSendBreaker } from './send-pacing.service';
import { TemplateService } from '../template/template.service';
import { renderedLength, renderTemplate, TemplateRenderError } from '../../common/utils/template-render';
import { createLogger } from '../../common/services/logger.service';
import { SsrfBlockedError, SSRF_BLOCKED_CLIENT_MESSAGE } from '../../common/security/ssrf-guard';
import { resolveFeatureFlags } from '../../config/feature-flags';
import { isUniqueViolation } from '../../common/utils/db-errors';
import { ChatMediaArchiveService } from '../chat-media/chat-media-archive.service';
import { LidMappingStoreService } from '../../engine/identity/lid-mapping-store.service';
import { resolveJidCandidates } from '../../engine/identity/jid-candidates';
import { captureSessionWrites, SessionWriteScope } from '../../common/utils/session-write-scope';

/** Default cap on a rendered template's final text; overridable via TEMPLATE_RENDER_MAX_CHARS. */
export const DEFAULT_TEMPLATE_RENDER_MAX_CHARS = 64 * 1024;

/**
 * True when this write's media is only a remote-URL pointer (a URL-based send, whose bytes the
 * engine fetches and discards). Merging such metadata onto an echo row would REPLACE bytes the
 * gateway already downloaded — wwjs enriches its own-send echo with the real payload — leaving a
 * row that renders as a bare marker and that the archive cannot use.
 */
function isUrlPointerMetadata(metadata: Record<string, unknown> | undefined): boolean {
  const data = (metadata as { media?: { data?: unknown } } | undefined)?.media?.data;
  return typeof data === 'string' && /^https?:\/\//i.test(data);
}

/** Persistence payload for one outbound row written by {@link MessageSendService.saveOutgoingMessage}. */
export interface SaveOutgoingMessageData {
  waMessageId?: string;
  chatId: string;
  body?: string;
  type: string;
  timestamp?: number;
  status?: MessageStatus;
  metadata?: Record<string, unknown>;
  /**
   * Quoted id for a send that quotes something. Folded into `metadata.quotedMessage` at the shared
   * persist rather than by each sender, so the nine send paths and `reply()` record one shape: a row
   * that quoted a message but records nothing is simply wrong history, and the dashboard reads this
   * key to render the quote preview. The quoted body is looked up there too, so a sender does not
   * have to remember; a quoted row with no text of its own (a caption-less image, say) still yields
   * '', which the preview renders as an empty box.
   */
  quotedMessageId?: string;
}

/**
 * Outbound sends are executed directly against the WhatsApp engine, not via a BullMQ queue.
 *
 * The engine is single-threaded per session (a Puppeteer page for the whatsapp-web.js adapter, a
 * single socket for Baileys) and is therefore itself the serialization point for that session's
 * outbound traffic. Routing sends through a queue would add request latency and a Redis hard
 * dependency to the hot path for no throughput benefit — the engine cannot go faster than it
 * already does. BullMQ is reserved for genuine side-effects that benefit from durable
 * retry/back-pressure (webhook delivery, integration ingress); see `QUEUE_NAMES` in
 * `queue-names.ts`, which intentionally defines no MESSAGE queue.
 *
 * Backpressure is applied at the edges instead: bulk sends self-throttle via
 * `delayBetweenMessages` (default 3s) and a per-process concurrent-batch cap (see
 * `BulkMessageService`), and the global throttler enforces per-route, per-client-IP rate limits.
 */
@Injectable()
export class MessageSendService {
  private readonly logger = createLogger('MessageSend');

  constructor(
    @InjectRepository(Message, 'data')
    private readonly messageRepository: Repository<Message>,
    private readonly sessionService: SessionService,
    private readonly engines: EngineRegistry,
    private readonly hookManager: HookManager,
    private readonly templateService: TemplateService,
    // Required, not @Optional: a missing pacing service would silently mean "no pacing", which is
    // the one failure mode this feature must not have. The service itself no-ops when disabled.
    private readonly pacing: SendPacingService,
    @Optional()
    private readonly configService?: ConfigService,
    // Optional so standalone constructions keep working; absent means outbound media is never
    // archived — the inline row copy and the read endpoint are unaffected either way.
    @Optional()
    private readonly chatMediaArchive?: ChatMediaArchiveService,
    // Optional for the same reason; absent means a quote is matched on the chat's phone and
    // literal forms only, never on its lid.
    @Optional()
    private readonly lidMappingStore?: LidMappingStoreService,
    // Optional for the same reason; absent means a quote is read from stored rows only, so a reply
    // sent while the quoted message's `message:received` hooks still run stores an empty quote.
    @Optional()
    private readonly messageProjector?: MessageProjector,
  ) {}

  async sendText(sessionId: string, dto: SendTextMessageDto): Promise<MessageResponseDto> {
    // Asking to suppress the preview AND to attach one is a contradiction, and guessing which half
    // the caller meant would send a message they did not ask for either way.
    if (dto.linkPreview === false && dto.customLinkPreview) {
      throw new BadRequestException('linkPreview: false cannot be combined with customLinkPreview');
    }
    const { message, finalDto, engine } = await this.applySendingGate(sessionId, 'text', dto, finalDto => ({
      chatId: finalDto.chatId,
      body: finalDto.text,
      type: 'text',
      quotedMessageId: finalDto.quotedMessageId,
    }));

    // Humanising "typing…" pause before the actual send (anti-automation signal). On by default;
    // SIMULATE_TYPING=false disables it.
    await this.simulateTypingIfEnabled(engine, finalDto.chatId, finalDto.text);

    let result: MessageResult;
    try {
      // The call is widened ONLY as far as the caller actually asked. A send with neither mentions
      // nor a preview choice keeps its two-argument shape, and one with mentions alone keeps its
      // three — trailing `undefined`s would be harmless to the engines but would rewrite the call
      // shape of every existing send for no behavioural gain.
      const { linkPreview, customLinkPreview, quotedMessageId } = finalDto;
      if (linkPreview !== undefined || customLinkPreview || quotedMessageId) {
        result = await engine.sendTextMessage(finalDto.chatId, finalDto.text, finalDto.mentions, {
          ...(linkPreview === undefined ? {} : { linkPreview }),
          ...(customLinkPreview ? { customPreview: customLinkPreview } : {}),
          ...(quotedMessageId ? { quotedMessageId } : {}),
        });
      } else if (finalDto.mentions?.length) {
        result = await engine.sendTextMessage(finalDto.chatId, finalDto.text, finalDto.mentions);
      } else {
        result = await engine.sendTextMessage(finalDto.chatId, finalDto.text);
      }
    } catch (error) {
      // The SEND itself failed — mark FAILED + fire message:failed (a post-send persistence fault is
      // handled separately by persistSentState and must NOT land here).
      return this.failSend(sessionId, 'text', message, finalDto, error);
    }

    // Note: the `message:sent` hook is emitted solely by the onMessageCreate wiring in
    // SessionEngineLifecycle (engine `message_create`, handled by MessageProjector) with a
    // consistent IncomingMessage payload for ALL sends (text, media,
    // and phone-composed), so it is intentionally not fired here to avoid a double dispatch.
    return this.persistSentState(message, result);
  }

  /**
   * Run the pre-send `message:sending` plugin gate for one outbound message and return the
   * (possibly plugin-modified) input with the session's engine, prepared data and durable PENDING
   * row, or throw BadRequestException if a plugin blocked the send.
   * Centralised so EVERY public sender in this class — text, media, extended (location/contact/
   * poll/sticker/reply/forward) — passes through the same moderation chokepoint, instead of only
   * `sendText`. The edit path is gated by the twin method in MessageService (the query side of
   * the send/query split), on the same core/hooks/sending-gate implementation shared with
   * StatusService.
   */
  private async applySendingGate<T extends object, P = undefined>(
    sessionId: string,
    type: string,
    input: T,
    buildPending: (finalDto: T, prepared: P) => SaveOutgoingMessageData | Promise<SaveOutgoingMessageData>,
    prepare?: (finalDto: T) => P,
  ): Promise<{ finalDto: T; engine: IWhatsAppEngine; prepared: P; message: Message }> {
    // Pacing runs BEFORE the plugin gate, so a send that policy forbids never reaches a plugin at
    // all — plugins should not be asked to moderate, or given the chance to rewrite, traffic that is
    // not going to be sent. The consequence is deliberate and documented in the hook contract: a
    // paced-out send fires no `message:sending`, so a plugin cannot observe it. Refusals are a 429
    // carrying `code: SEND_PACING_LIMITED`; a plugin veto stays a 400.
    // Every gated sender's DTO addresses its destination as `chatId` except forward, which uses
    // `toChatId` — without the fallback a forward skipped the cold-reachout gate entirely, while
    // its persisted row still drained the cold budget. Edit carries a chatId too; the edited
    // message's own row already makes that chat warm, so the gate is a no-op there.
    const target = input as { chatId?: string; toChatId?: string };
    const lifetime = captureSessionWrites(
      this.messageRepository.manager?.connection ?? this.messageRepository,
      sessionId,
    );
    let release: SettleAdmission | undefined;
    // Everything a sender does before its PENDING row is written runs in here (the plugin gate, the
    // engine lookup, preparation and initial persistence), so a failure hands its pacing admission back: with no
    // row it never counts, and holding it would refuse the caller's next send near the cap.
    let persisted = false;
    try {
      release = await this.pacing.assertSendAllowed(sessionId, target.chatId ?? target.toChatId, {
        whilePreparing: true,
      });
      if (release) lifetime.onRetire(release);
      lifetime.assertCurrent();
      const finalDto = await applySendingGate(this.hookManager, sessionId, type, input, 'MessageService');
      lifetime.assertCurrent();
      const engine = this.getEngine(sessionId);
      const prepared = prepare?.(finalDto) as P;
      const message = await this.saveOutgoingMessage(sessionId, await buildPending(finalDto, prepared), lifetime);
      lifetime.assertCurrent();
      persisted = true;
      return { finalDto, engine, prepared, message };
    } finally {
      release?.(persisted);
      lifetime.close();
    }
  }

  /**
   * Mark a send as FAILED, fire the `message:failed` plugin hook, then throw a client-facing error.
   * Centralised so failure notifications cover every sender (previously only `sendText` fired
   * `message:failed`; media/extended sends failed silently to plugins). The post-send persistence-fault
   * path (persistSentState) deliberately does NOT route here — a message the engine already accepted
   * must never be reported as a send failure.
   */
  private async failSend(
    sessionId: string,
    type: string,
    message: Message,
    input: unknown,
    error: unknown,
  ): Promise<never> {
    try {
      // Only failures that say something about the account's standing feed the breaker: adapters also
      // raise client-fault and engine-state errors from inside this call (a blocked media URL, an
      // unsupported capability, a disconnected socket), and counting those let a client sending bad
      // requests trip the breaker on a healthy session.
      if (countsTowardSendBreaker(error)) {
        this.pacing.recordSendFailure(sessionId);
        // The same classification picks the failures worth a log line. Otherwise an engine-side failure
        // leaves only Nest's generic `[ExceptionsHandler]` line, with no session, chat or message type to
        // correlate it with.
        this.logger.warn(`Send failed in the engine (${type})`, {
          sessionId,
          chatId: message.chatId,
          messageId: message.id,
          error: error instanceof Error ? `${error.name}: ${error.message}` : String(error),
          // An EnginePageError keeps the full in-page summary (stack, own properties) here only.
          ...(error instanceof Error && error.cause instanceof Error ? { cause: error.cause.message } : {}),
        });
      }
      await this.saveFailedMessage(message);
      // Sanitize the hook payload: an SSRF block's raw .message names the resolved internal address
      // (a recon/DNS-rebind oracle); the client-facing throw below already maps it to a generic
      // message via toClientFacingError, and the message:failed hook must not expose more than the
      // client sees. Now that every media/extended sender routes here, this is the chokepoint that
      // keeps SSRF detail out of plugin hands (bulk does the same via sanitizeBatchError).
      const hookError =
        error instanceof SsrfBlockedError
          ? SSRF_BLOCKED_CLIENT_MESSAGE
          : error instanceof Error
            ? error.message
            : String(error);
      await this.hookManager.execute(
        'message:failed',
        { sessionId, error: hookError, input, type },
        { sessionId, source: 'MessageService' },
      );
      throw this.toClientFacingError(error);
    } catch (failure) {
      // HTTP status alone cannot prove whether an engine accepted the message before failing.
      throw markEngineSendFailure(failure);
    }
  }

  /**
   * Resolve a stored template, render its body (with optional header/footer
   * flattened using newlines) using the supplied variables, and delegate to the
   * existing {@link sendText} path so plugin hooks, persistence, and status
   * tracking are reused. Throws NotFoundException when the identifier matches
   * nothing, BadRequestException when neither templateId nor templateName is
   * given.
   *
   * The FINAL rendered text is capped at template.renderMaxChars (default 64 KiB): caller-supplied
   * variables can inflate a small template unboundedly, so an over-cap render is rejected with a
   * 400 naming the limit rather than truncated silently or pushed to the engine/DB as-is. The length
   * is measured before anything is rendered, so a refused request never allocates the oversized text.
   */
  async sendTemplate(sessionId: string, dto: SendTemplateMessageDto): Promise<MessageResponseDto> {
    const template = await this.templateService.resolve(sessionId, {
      templateId: dto.templateId,
      templateName: dto.templateName,
    });

    const vars = dto.vars ?? {};
    const parts = [template.header, template.body, template.footer].filter(
      (segment): segment is string => segment != null && segment.length > 0,
    );
    const separator = '\n\n';

    const maxChars =
      this.configService?.get<number>('template.renderMaxChars', DEFAULT_TEMPLATE_RENDER_MAX_CHARS) ??
      DEFAULT_TEMPLATE_RENDER_MAX_CHARS;
    let text: string;
    try {
      const length =
        parts.reduce((sum, part) => sum + renderedLength(part, vars), 0) +
        separator.length * Math.max(0, parts.length - 1);
      if (length > maxChars) {
        throw new BadRequestException(
          `Rendered template is ${length} characters, over the ${maxChars}-character limit`,
        );
      }
      text = parts.map(part => renderTemplate(part, vars)).join(separator);
    } catch (error) {
      if (error instanceof TemplateRenderError) throw new BadRequestException(error.message);
      throw error;
    }

    return this.sendText(sessionId, {
      chatId: dto.chatId,
      text,
      mentions: dto.mentions,
      linkPreview: dto.linkPreview,
    });
  }

  async sendImage(sessionId: string, dto: SendMediaMessageDto): Promise<MessageResponseDto> {
    const {
      message,
      finalDto,
      engine,
      prepared: media,
    } = await this.applySendingGate(
      sessionId,
      'image',
      dto,
      (finalDto, media) => ({
        chatId: finalDto.chatId,
        body: finalDto.caption || '',
        type: 'image',
        quotedMessageId: finalDto.quotedMessageId,
        metadata: {
          media: { mimetype: finalDto.mimetype, filename: finalDto.filename, data: media.data },
        },
      }),
      (d: SendMediaMessageDto) => this.buildMediaInput(d),
    );

    let result: MessageResult;
    try {
      result = await engine.sendImageMessage(finalDto.chatId, media);
    } catch (error) {
      return this.failSend(sessionId, 'image', message, finalDto, error);
    }
    return this.persistSentState(message, result);
  }

  async sendVideo(sessionId: string, dto: SendMediaMessageDto): Promise<MessageResponseDto> {
    const {
      message,
      finalDto,
      engine,
      prepared: media,
    } = await this.applySendingGate(
      sessionId,
      'video',
      dto,
      (finalDto, media) => ({
        chatId: finalDto.chatId,
        body: finalDto.caption || '',
        type: 'video',
        quotedMessageId: finalDto.quotedMessageId,
        metadata: {
          media: { mimetype: finalDto.mimetype, filename: finalDto.filename, data: media.data },
        },
      }),
      (d: SendMediaMessageDto) => this.buildMediaInput(d),
    );

    let result: MessageResult;
    try {
      result = await engine.sendVideoMessage(finalDto.chatId, media);
    } catch (error) {
      return this.failSend(sessionId, 'video', message, finalDto, error);
    }
    return this.persistSentState(message, result);
  }

  async sendAudio(sessionId: string, dto: SendAudioMessageDto): Promise<MessageResponseDto> {
    // Label a PTT send 'voice' in the gate (not 'audio') so message:sending, message:failed, and the
    // persisted row all carry the same type for one outbound voice note — failSend and the saved row
    // already use `finalDto.ptt ? 'voice' : 'audio'`.
    const {
      message,
      finalDto,
      engine,
      prepared: { media },
    } = await this.applySendingGate(
      sessionId,
      dto.ptt ? 'voice' : 'audio',
      dto,
      (finalDto, { audioDto, media }) => ({
        chatId: finalDto.chatId,
        type: finalDto.ptt ? 'voice' : 'audio',
        metadata: {
          media: { mimetype: audioDto.mimetype, filename: finalDto.filename, data: media.data },
        },
        quotedMessageId: finalDto.quotedMessageId,
      }),
      (gated: SendAudioMessageDto) => {
        // Voice notes need a real audio codec; default to ogg/opus when the caller omits a mimetype so the
        // wire message and the persisted record agree. Resolved BEFORE buildMediaInput so its base64
        // mimetype guard sees the effective type. buildMediaInput itself stays generic (shared by all media).
        const audioDto = gated.ptt && !gated.mimetype ? { ...gated, mimetype: 'audio/ogg; codecs=opus' } : gated;
        const media = this.buildMediaInput(audioDto);
        media.ptt = gated.ptt;
        return { audioDto, media };
      },
    );

    let result: MessageResult;
    try {
      result = await engine.sendAudioMessage(finalDto.chatId, media);
    } catch (error) {
      return this.failSend(sessionId, finalDto.ptt ? 'voice' : 'audio', message, finalDto, error);
    }
    return this.persistSentState(message, result);
  }

  async sendDocument(sessionId: string, dto: SendMediaMessageDto): Promise<MessageResponseDto> {
    const {
      message,
      finalDto,
      engine,
      prepared: media,
    } = await this.applySendingGate(
      sessionId,
      'document',
      dto,
      (finalDto, media) => ({
        chatId: finalDto.chatId,
        body: finalDto.caption || finalDto.filename || '',
        type: 'document',
        quotedMessageId: finalDto.quotedMessageId,
        metadata: {
          media: { mimetype: finalDto.mimetype, filename: finalDto.filename, data: media.data },
        },
      }),
      (d: SendMediaMessageDto) => this.buildMediaInput(d),
    );

    let result: MessageResult;
    try {
      result = await engine.sendDocumentMessage(finalDto.chatId, media);
    } catch (error) {
      return this.failSend(sessionId, 'document', message, finalDto, error);
    }
    return this.persistSentState(message, result);
  }

  async sendLocation(
    sessionId: string,
    dto: {
      chatId: string;
      latitude: number;
      longitude: number;
      description?: string;
      address?: string;
      quotedMessageId?: string;
    },
  ): Promise<MessageResponseDto> {
    const { message, finalDto, engine } = await this.applySendingGate(sessionId, 'location', dto, finalDto => ({
      chatId: finalDto.chatId,
      body: `📍 ${finalDto.description || 'Location'}`,
      type: 'location',
      quotedMessageId: finalDto.quotedMessageId,
    }));

    let result: MessageResult;
    try {
      result = await engine.sendLocationMessage(finalDto.chatId, {
        latitude: finalDto.latitude,
        longitude: finalDto.longitude,
        description: finalDto.description,
        address: finalDto.address,
        quotedMessageId: finalDto.quotedMessageId,
      });
    } catch (error) {
      return this.failSend(sessionId, 'location', message, finalDto, error);
    }
    return this.persistSentState(message, result);
  }

  async sendContact(
    sessionId: string,
    dto: { chatId: string; contactName: string; contactNumber: string; quotedMessageId?: string },
  ): Promise<MessageResponseDto> {
    const { message, finalDto, engine } = await this.applySendingGate(sessionId, 'contact', dto, finalDto => ({
      chatId: finalDto.chatId,
      body: `📇 ${finalDto.contactName}`,
      type: 'contact',
      quotedMessageId: finalDto.quotedMessageId,
    }));

    let result: MessageResult;
    try {
      result = await engine.sendContactMessage(finalDto.chatId, {
        name: finalDto.contactName,
        number: finalDto.contactNumber,
        quotedMessageId: finalDto.quotedMessageId,
      });
    } catch (error) {
      return this.failSend(sessionId, 'contact', message, finalDto, error);
    }
    return this.persistSentState(message, result);
  }

  async sendPoll(
    sessionId: string,
    dto: { chatId: string; name: string; options: string[]; allowMultipleAnswers?: boolean; quotedMessageId?: string },
  ): Promise<MessageResponseDto> {
    const { message, finalDto, engine } = await this.applySendingGate(sessionId, 'poll', dto, finalDto => ({
      chatId: finalDto.chatId,
      body: `📊 ${finalDto.name}`,
      type: 'poll',
      metadata: {
        poll: {
          name: finalDto.name,
          options: [...finalDto.options],
          allowMultipleAnswers: finalDto.allowMultipleAnswers === true,
        },
      },
      quotedMessageId: finalDto.quotedMessageId,
    }));

    let result: MessageResult;
    try {
      result = await engine.sendPollMessage(finalDto.chatId, {
        name: finalDto.name,
        options: finalDto.options,
        allowMultipleAnswers: finalDto.allowMultipleAnswers === true,
        quotedMessageId: finalDto.quotedMessageId,
      });
    } catch (error) {
      return this.failSend(sessionId, 'poll', message, finalDto, error);
    }
    return this.persistSentState(message, result);
  }

  async sendSticker(sessionId: string, dto: SendMediaMessageDto): Promise<MessageResponseDto> {
    const {
      message,
      finalDto,
      engine,
      prepared: media,
    } = await this.applySendingGate(
      sessionId,
      'sticker',
      dto,
      (finalDto, media) => ({
        chatId: finalDto.chatId,
        type: 'sticker',
        quotedMessageId: finalDto.quotedMessageId,
        metadata: {
          media: { mimetype: finalDto.mimetype, filename: finalDto.filename, data: media.data },
        },
      }),
      (d: SendMediaMessageDto) => this.buildMediaInput(d),
    );

    let result: MessageResult;
    try {
      result = await engine.sendStickerMessage(finalDto.chatId, media);
    } catch (error) {
      return this.failSend(sessionId, 'sticker', message, finalDto, error);
    }
    return this.persistSentState(message, result);
  }

  async reply(
    sessionId: string,
    dto: { chatId: string; quotedMessageId: string; text: string; mentions?: string[] },
  ): Promise<MessageResponseDto> {
    const { message, finalDto, engine } = await this.applySendingGate(sessionId, 'reply', dto, async finalDto => {
      const quotedBody = await this.resolveQuotedBody(sessionId, finalDto.quotedMessageId, finalDto.chatId);
      return {
        chatId: finalDto.chatId,
        body: finalDto.text,
        type: 'text',
        metadata: {
          quotedMessage: { id: finalDto.quotedMessageId, body: quotedBody },
        },
      };
    });

    let result: MessageResult;
    try {
      // Widened only as far as the caller asked, exactly like the send path: a reply with no tags
      // keeps its three-argument shape.
      result = finalDto.mentions?.length
        ? await engine.replyToMessage(finalDto.chatId, finalDto.quotedMessageId, finalDto.text, finalDto.mentions)
        : await engine.replyToMessage(finalDto.chatId, finalDto.quotedMessageId, finalDto.text);
    } catch (error) {
      return this.failSend(sessionId, 'reply', message, finalDto, error);
    }
    return this.persistSentState(message, result);
  }

  async clickButton(
    sessionId: string,
    dto: { chatId: string; messageId: string; buttonId: string; text?: string },
  ): Promise<MessageResponseDto> {
    const { message, finalDto, engine } = await this.applySendingGate(
      sessionId,
      'click-button',
      dto,
      async finalDto => {
        const promptBody = await this.resolveQuotedBody(sessionId, finalDto.messageId, finalDto.chatId);
        return {
          chatId: finalDto.chatId,
          body: finalDto.text || finalDto.buttonId,
          type: 'text',
          metadata: {
            quotedMessage: { id: finalDto.messageId, body: promptBody },
            button: { id: finalDto.buttonId, text: finalDto.text },
          },
        };
      },
    );

    let result: MessageResult;
    try {
      result = await engine.clickButton(finalDto.chatId, finalDto.messageId, finalDto.buttonId, finalDto.text);
    } catch (error) {
      return this.failSend(sessionId, 'click-button', message, finalDto, error);
    }
    // The engine resolves the visible label from the stored prompt when the caller omitted `text`.
    // Persist that label (not the raw buttonId) so the row agrees with what went on the wire.
    if (result.body) {
      message.body = result.body;
      message.metadata = {
        ...(message.metadata ?? {}),
        button: { id: finalDto.buttonId, text: result.body },
      };
    }
    return this.persistSentState(
      message,
      result,
      result.body
        ? { body: result.body, metadata: message.metadata as QueryDeepPartialEntity<Record<string, unknown>> }
        : undefined,
    );
  }

  async forward(
    sessionId: string,
    dto: { fromChatId: string; toChatId: string; messageId: string },
  ): Promise<MessageResponseDto> {
    const { message, finalDto, engine } = await this.applySendingGate(sessionId, 'forward', dto, finalDto => ({
      chatId: finalDto.toChatId,
      body: '[Forwarded]',
      type: 'forward',
    }));

    let result: MessageResult;
    try {
      result = await engine.forwardMessage(finalDto.fromChatId, finalDto.toChatId, finalDto.messageId);
    } catch (error) {
      return this.failSend(sessionId, 'forward', message, finalDto, error);
    }
    // persistSentState preserves the empty-id rule: a forward whose engine couldn't recover the sent
    // copy's id leaves waMessageId NULL so no ack mis-matches it.
    return this.persistSentState(message, result);
  }

  /**
   * The body of the message a send is quoting, for the dashboard's quote preview. Best-effort in
   * every direction: an id that names nothing stored (evicted, or sent from the phone before this
   * gateway saw the chat) and a read that fails both answer '', because a preview is never worth
   * failing a send over. The row is looked up by engine id within the session. A reply and a button
   * click answer a message in the chat they send into, so for them `chatId` also restricts the lookup
   * to that chat (any of its phone, lid or group forms): the pending row is saved before the engine
   * refuses a cross-chat quote, and copying a foreign body would store it under a chat a
   * chat-restricted key may use. The send routes may quote across chats, and the guard refuses a
   * chat-restricted key any quotedMessageId there, so they pass no chat. While the quoted message's
   * `message:received` hooks are still running it has no row yet, so the copy that hook chain
   * carries answers instead, under the same chat restriction.
   */
  private async resolveQuotedBody(sessionId: string, quotedMessageId: string, chatId?: string): Promise<string> {
    try {
      const store = this.lidMappingStore;
      const expanded = chatId
        ? await resolveJidCandidates(
            chatId,
            store && {
              resolveLid: lid => store.findPhoneForLid(lid),
              lidsForPhone: phone => store.findLidsForPhone(phone),
            },
          )
        : [];
      // A `message:received` hook that answers the message runs before its row is written. A hook
      // rewrite is checked for its id and chatId only, so a body that is not text quotes as ''.
      const inFlight = this.messageProjector?.inFlightInbound(sessionId, quotedMessageId);
      if (inFlight && (!chatId || inFlight.chatId === chatId || expanded.includes(inFlight.chatId))) {
        return typeof inFlight.body === 'string' ? inFlight.body : '';
      }
      const quoted = await this.messageRepository.findOne({
        where: chatId
          ? { sessionId, chatId: In([...new Set([chatId, ...expanded])]), waMessageId: quotedMessageId }
          : { sessionId, waMessageId: quotedMessageId },
      });
      return quoted?.body || '';
    } catch (err) {
      this.logger.warn(`Failed to resolve quoted message ${quotedMessageId}`, { error: String(err) });
      return '';
    }
  }

  /**
   * Save outgoing message to database.
   * When called before sending, creates a record with PENDING status; bulk send reuses this after a
   * successful send (status SENT) so batch messages are persisted like single sends.
   *
   * A caller that already knows the engine id races the own-send echo on
   * UNIQUE(sessionId, waMessageId) — only the bulk path does today, since every single send persists
   * its PENDING row before the id exists. Losing that race merges onto the echo's row rather than
   * failing, mirroring `persistSentState`: the echo carries only what the engine reported (for a
   * Baileys API send, a media-less marker), so dropping this write would lose the media payload.
   */
  async saveOutgoingMessage(
    sessionId: string,
    data: SaveOutgoingMessageData,
    lifetime?: SessionWriteScope,
  ): Promise<Message> {
    const scope =
      lifetime ?? captureSessionWrites(this.messageRepository.manager?.connection ?? this.messageRepository, sessionId);
    try {
      const session = await this.sessionService.findOne(sessionId);
      // Resolved here rather than in each sender: reply and click-button build their own
      // `metadata.quotedMessage` and never reach this branch, so every OTHER quoting sender (media,
      // location, contact, poll, quoted text) used to persist an id with an empty body and the
      // dashboard drew a blank quote box above the message.
      const quotedMessage = data.quotedMessageId
        ? { id: data.quotedMessageId, body: await this.resolveQuotedBody(sessionId, data.quotedMessageId) }
        : undefined;
      const message = this.messageRepository.create({
        sessionId,
        // An engine that sent a message but could not read its id back reports an empty id (see the
        // whatsapp-web.js adapter's `toMessageResult`). Store NULL rather than '': the
        // (sessionId, waMessageId) unique index is not partial, so a second id-less send in the same
        // session collides on '' while NULLs stay exempt — and in the bulk path that violation is
        // swallowed into a warning, losing the row silently. Normalizing at this one chokepoint covers
        // every caller instead of relying on each to remember.
        waMessageId: data.waMessageId || undefined,
        chatId: data.chatId,
        from: session?.phone || 'me',
        to: data.chatId,
        body: data.body,
        type: data.type,
        direction: MessageDirection.OUTGOING,
        timestamp: data.timestamp,
        status: data.status ?? MessageStatus.PENDING,
        metadata: quotedMessage ? { ...data.metadata, quotedMessage } : data.metadata,
      });
      // No transaction of its own: the unique violation handled below is routine (the own-send echo wins the
      // race), and on SQLite's single shared connection its rollback would discard what other callers wrote
      // while it was open, after they were told it was stored.
      const saved = await scope
        .write(() => this.messageRepository.save(message, { transaction: false }))
        .catch(async (err: unknown) => {
          const waMessageId = message.waMessageId;
          if (!waMessageId || !isUniqueViolation(err)) throw err;
          // No `status` here on purpose. The row this collides with is the own-send echo's, inserted
          // SENT, and the ack path advances it forward-only (ackStatusTransitionFrom). This write only
          // ever carries PENDING or SENT, so it can never be an upgrade: it is a no-op, or it drags a
          // DELIVERED/READ row back to SENT when an ack won the race. Leave the delivery state to the
          // one writer that owns it.
          const patch: QueryDeepPartialEntity<Message> = {
            timestamp: message.timestamp,
          };
          // Only when this write actually carries metadata worth merging: a text item must not blank
          // the echo's, and a URL pointer must not replace bytes the engine already downloaded.
          const metadata = message.metadata;
          if (metadata && !isUrlPointerMetadata(metadata)) {
            try {
              await updateMessageMetadata(this.messageRepository, { sessionId, waMessageId }, current =>
                mergeSentMetadata(current, metadata),
              );
            } catch (error) {
              if (message.status !== MessageStatus.SENT) throw error;
              this.logger.warn(`Merging sent metadata onto the echo row failed (id=${waMessageId})`, {
                error: error instanceof Error ? error.message : String(error),
              });
              // The bulk engine has already sent this item. Keep its media in an id-less SENT row
              // when the echo cannot accept it, instead of losing the only payload-bearing copy.
              return scope.write(() =>
                this.messageRepository.save(this.messageRepository.create({ ...message, waMessageId: undefined })),
              );
            }
          }
          if (message.timestamp !== undefined) await this.messageRepository.update({ sessionId, waMessageId }, patch);
          const surviving = await this.messageRepository.findOne({ where: { sessionId, waMessageId } });
          if (!surviving) throw err;
          return surviving;
        });
      this.emitPersisted(sessionId, saved);
      return saved;
    } finally {
      if (!lifetime) scope.close();
    }
  }

  // Fire-and-forget: a plugin handler must never break the send path. The built-in FTS search provider
  // is DB-synced and does NOT consume this; it exists for plugin providers (Spec 2) + general use.
  // Emitted for EVERY persisted state of an outbound row — the initial PENDING write AND each later
  // transition (SENT / FAILED / merge) — so a provider's copy never stays stuck at PENDING (#906).
  // The payload is a shallow snapshot: the same entity instance is mutated as the send progresses
  // (PENDING → SENT/FAILED), and fire-and-forget execution must still see the state at emission time.
  //
  // Outbound archiving rides the same chokepoint rather than a call at each of the four persist
  // sites: every terminal state of an outbound row passes here. Gated on SENT because a PENDING row
  // may still be deleted by the dedup merge or rewritten by the pending reaper, and a FAILED one has
  // had its payload stripped — archiving either would strand a file the row never points at.
  //
  // Hook emissions keep `source: 'MessageService'` — the string is part of the observable hook
  // contract plugins may filter on, so the send seam must not change it.
  private emitPersisted(sessionId: string, message: Message): void {
    void this.hookManager
      .execute('message:persisted', { sessionId, message: { ...message } }, { sessionId, source: 'MessageService' })
      .catch(() => undefined);
    if (message.status === MessageStatus.SENT && this.archiveOutboundEnabled) {
      void this.chatMediaArchive?.archive(message).catch(() => undefined);
    }
  }

  /** Whether media this account sent is archived too — a sub-flag of the archive itself. */
  private get archiveOutboundEnabled(): boolean {
    return this.configService?.get<boolean>('chatMedia.archiveOutbound', false) === true;
  }

  /**
   * Persist a send as FAILED, dropping any outbound media payload first. A failed row's media base64
   * (often multi-MB) is never displayed or retried, so keeping it only bloats the messages table; the
   * mimetype/filename are kept so the row still describes what was attempted.
   */
  private async saveFailedMessage(message: Message): Promise<void> {
    const media = (message.metadata as { media?: { data?: unknown } } | undefined)?.media;
    if (media) {
      delete media.data;
    }
    message.status = MessageStatus.FAILED;
    const result = await this.messageRepository.update(
      { id: message.id, sessionId: message.sessionId },
      {
        status: MessageStatus.FAILED,
        metadata: message.metadata as QueryDeepPartialEntity<Record<string, unknown>>,
      },
    );
    if (!result.affected) return;
    // Reconcile the earlier PENDING emission (#906): a provider must see the terminal FAILED state.
    this.emitPersisted(message.sessionId, message);
  }

  /**
   * Persist the SENT state AFTER the engine has already accepted the message. The send already
   * succeeded, so a failure to write the SENT row must NOT be surfaced as a send failure — a transient
   * DB fault would otherwise mark a delivered message permanently FAILED and (for text) fire
   * `message:failed`. Log and return success instead.
   */
  private async persistSentState(
    message: Message,
    result: MessageResult,
    // Columns a sender changed in memory after its PENDING insert. The write below is an UPDATE of
    // fixed columns, so anything not listed here (the resolved button label, for one) is never stored.
    // `metadata` is listed only when it changed: the insert already stored it, and a base64 media
    // payload inside it would otherwise be written a second time on every send.
    changed: Pick<QueryDeepPartialEntity<Message>, 'body' | 'metadata'> = {},
  ): Promise<MessageResponseDto> {
    // A send whose engine couldn't read the sent message's id back reports an empty id — a forward that
    // can't recover the copy, or a WhatsApp Web build that renamed the id field out from under the
    // engine. Leave waMessageId unset (NULL) so no ack mis-matches it.
    // The engine accepted the message, so whatever streak the breaker was tracking is over. Recorded
    // here rather than at each call site for the same reason failSend is: one funnel, twelve senders.
    this.pacing.recordSendSuccess(message.sessionId);
    if (result.id) message.waMessageId = result.id;
    message.status = MessageStatus.SENT;
    message.timestamp = result.timestamp;
    try {
      // No transaction of its own, for the reason given at the first save of this message.
      const sent: QueryDeepPartialEntity<Message> = {
        ...changed,
        waMessageId: message.waMessageId,
        status: message.status,
        timestamp: message.timestamp,
      };
      // Guarded on the row still being PENDING, so the common write carries no metadata. A row the pending
      // reaper failed while the engine was still answering has lost its media payload and gained a marker:
      // it is written again, unguarded, with the metadata the insert stored. No row at all means the
      // session was deleted under this send.
      let updated = await this.messageRepository.update(
        { id: message.id, sessionId: message.sessionId, status: MessageStatus.PENDING },
        sent,
      );
      if (!updated.affected) {
        updated = await this.messageRepository.update(
          { id: message.id, sessionId: message.sessionId },
          { ...sent, metadata: message.metadata as QueryDeepPartialEntity<Record<string, unknown>> },
        );
      }
      if (!updated.affected) return { messageId: result.id, timestamp: result.timestamp };
      // Reconcile the earlier PENDING emission with the finalized row (#906).
      this.emitPersisted(message.sessionId, message);
    } catch (persistError) {
      if (result.id && isUniqueViolation(persistError)) {
        // The engine's own-send echo (onMessageCreate) won the race and already persisted a row with
        // this waMessageId. That row carries only what the engine reported — for a Baileys API send,
        // a media-less marker — so merge our SENT state AND our metadata (the actual media payload)
        // onto it BEFORE dropping this redundant PENDING row, or the payload-bearing row is the one
        // that gets deleted and the media is gone after a reload.
        // Best-effort throughout: the send itself already succeeded.
        this.logger.debug(
          `Send echo already persisted ${result.id}; merging state and dropping the redundant pending row`,
          {
            messageId: message.id,
          },
        );
        // `status` is deliberately absent: the echo row is already SENT, and an ack that landed
        // first has advanced it further. Writing SENT here would undo that. See the sibling merge
        // in saveOutgoingMessage.
        const patch: QueryDeepPartialEntity<Message> = { timestamp: result.timestamp };
        const metadata = message.metadata;
        let metadataMerged = true;
        if (metadata && !isUrlPointerMetadata(metadata)) {
          await updateMessageMetadata(
            this.messageRepository,
            { sessionId: message.sessionId, waMessageId: result.id },
            current => mergeSentMetadata(current, metadata),
          ).catch(err => {
            metadataMerged = false;
            this.logger.warn(`Merging media onto the echo-persisted row failed (id=${result.id})`, {
              error: err instanceof Error ? err.message : String(err),
            });
          });
        }
        if (!metadataMerged) {
          // Keep the payload-bearing row when the echo merge fails. Mark it SENT without the
          // conflicting engine id so the pending reaper cannot strip successfully sent media. This is the
          // row that survives, so it carries what the send resolved too (a clicked button's label).
          await this.messageRepository
            .update(
              { id: message.id, status: MessageStatus.PENDING },
              { status: MessageStatus.SENT, timestamp: result.timestamp, ...changed },
            )
            .catch(err =>
              this.logger.warn(`Preserving the sent media row failed (id=${message.id})`, {
                error: err instanceof Error ? err.message : String(err),
              }),
            );
          const retained = await this.messageRepository.findOne({ where: { id: message.id } }).catch(() => null);
          if (retained) this.emitPersisted(message.sessionId, retained);
          return { messageId: result.id, timestamp: result.timestamp };
        }
        await this.messageRepository
          .update({ sessionId: message.sessionId, waMessageId: result.id }, patch)
          .catch(err =>
            this.logger.warn(`Merging SENT state onto the echo-persisted row failed (id=${result.id})`, {
              error: err instanceof Error ? err.message : String(err),
            }),
          );
        await this.messageRepository.delete({ id: message.id }).catch(() => undefined);
        // Reconcile provider indexes (#906): upsert the surviving echo row (now carrying our SENT
        // state + media) and drop the ghost PENDING document this redundant row produced earlier.
        const surviving = await this.messageRepository
          .findOne({ where: { sessionId: message.sessionId, waMessageId: result.id } })
          .catch(() => null);
        if (surviving) this.emitPersisted(message.sessionId, surviving);
        void this.hookManager
          .execute(
            'message:deleted',
            { sessionId: message.sessionId, message: { ...message } },
            { sessionId: message.sessionId, source: 'MessageService' },
          )
          .catch(() => undefined);
      } else {
        this.logger.warn(`Persisting SENT state failed after a successful send (id=${result.id})`, {
          error: persistError instanceof Error ? persistError.message : String(persistError),
        });
      }
    }
    return { messageId: result.id, timestamp: result.timestamp };
  }

  private getEngine(sessionId: string) {
    return this.engines.require(
      sessionId,
      () => new BadRequestException(`Session '${sessionId}' is not active. Start the session first.`),
    );
  }

  /**
   * Humanising delay: show the engine's typing indicator and pause for a length-scaled, jittered
   * interval before the real send, so automated single sends don't look instantaneous (anti-ban).
   * ON by default — set `SIMULATE_TYPING=false` to disable. Engine-agnostic (goes through
   * `sendChatState`) and strictly best-effort — it never throws and never blocks the send if presence
   * fails or the engine has no presence concept. `SIMULATE_TYPING_MAX_MS` (default 5000) caps the pause.
   * Note: this covers single sends only; bulk sends use their own `delayBetweenMessages` throttle.
   */
  private async simulateTypingIfEnabled(engine: IWhatsAppEngine, chatId: string, text: string): Promise<void> {
    const { simulateTyping, simulateTypingMaxMs } = resolveFeatureFlags(this.configService);
    if (!simulateTyping) return;
    try {
      await engine.sendChatState(chatId, 'typing');
      const maxMs = simulateTypingMaxMs;
      const planned = Math.min(maxMs, 500 + text.length * 45);
      const jittered = Math.round(planned * (0.85 + Math.random() * 0.3)); // ±15% so it isn't metronomic
      await new Promise(resolve => setTimeout(resolve, Math.min(maxMs, jittered)));
    } catch (error) {
      this.logger.warn(`simulateTyping skipped: ${error instanceof Error ? error.message : String(error)}`);
    }
  }

  /**
   * Map a blocked outbound media fetch (SSRF guard) to an HTTP 400 so a
   * caller-supplied internal/unsafe URL returns a client error instead of a 500.
   * The raw guard message names the resolved internal IP (a recon/DNS-rebind oracle), so return a
   * generic message to the client and keep the detail in the server log only. Others pass through.
   */
  private toClientFacingError(error: unknown): unknown {
    if (error instanceof SsrfBlockedError) {
      this.logger.warn(`Outbound media fetch blocked by SSRF guard: ${error.message}`);
      return new BadRequestException(SSRF_BLOCKED_CLIENT_MESSAGE);
    }
    return error;
  }

  private buildMediaInput(dto: SendMediaMessageDto): MediaInput {
    const { mimetype, data } = resolveMediaBody(dto, {
      fallbackMimetype: 'application/octet-stream',
      requireMimetypeForBase64: true,
      checkUrl: true,
    });
    return {
      mimetype,
      data,
      filename: dto.filename,
      caption: dto.caption,
      mentions: dto.mentions,
      quotedMessageId: dto.quotedMessageId,
    };
  }
}