Free, Open Source, Self-Hosted WhatsApp API Gateway
TypeScript apibotgatewayself-hostedwhatsappwhatsapp-apiwhatsapp-automationwhatsapp-botwhatsapp-gatewaywhatsapp-gateway-apiwhatsapp-webwhatsapp-web-api
import { MessageMedia, MessageTypes, type Client, type Message } from 'whatsapp-web.js';
import {
CustomLinkPreview,
IncomingMessage,
LocationInput,
ContactCard,
DeliveryStatus,
MediaInput,
MessageContact,
MessageReaction,
MessageResult,
PollInput,
Quotable,
} from '../interfaces/whatsapp-engine.interface';
import { MessageWithReactions, SerializedWid, readWid } from '../types/whatsapp-web-js.types';
import { BadRequestException, NotImplementedException } from '@nestjs/common';
import { MessageNotFoundError } from '../../common/errors/message-not-found.error';
import { EngineRefusedError } from '../../common/errors/engine-refused.error';
import { loadRemoteMediaBuffer } from '../../common/media/load-remote-media';
import { chatKind, userPart } from '../identity/wa-id';
import {
chatHistoryMediaBudgetBytes,
coerceDeclaredSize,
inboundMediaMaxBytes,
ingestMediaBudgetBytes,
isMediaDownloadEnabled,
} from './inbound-media-cap';
import { buildIncomingMessageBase, mapContactFields } from './message-mapper';
import { buildVCard } from './vcard';
import { EngineNotSupportedError } from '../../common/errors/engine-not-supported.error';
import { RecipientUnreachableError } from '../../common/errors/recipient-unreachable.error';
import { type WwebjsEngineHost, requireClient, withPage } from './wwebjs-host';
import { toCapturedPageError } from './wwebjs-lifecycle';
/**
* Map a whatsapp-web.js MessageAck integer to the neutral DeliveryStatus.
* wwebjs: -1 ERROR, 0 PENDING, 1 SERVER (sent), 2 DEVICE (delivered), 3 READ, 4 PLAYED.
* PLAYED collapses to `read` (preserving prior behaviour, which treated ack>=3 as read).
*/
export function wwebjsAckToDeliveryStatus(ack: number): DeliveryStatus {
if (ack < 0) return 'failed';
if (ack >= 3) return 'read';
if (ack === 2) return 'delivered';
if (ack === 1) return 'sent';
return 'pending';
}
/**
* Extract call detail from a whatsapp-web.js `call_log` message, or `undefined` for any other type.
* The public Message wrapper doesn't expose call fields, so we read them off the raw `_data`. An
* incoming call (`!fromMe`) with no recorded `callDuration` was never answered → missed; an outgoing
* call is never "missed". Used by getChatHistory, where `call_log` entries actually appear.
*/
export function extractWwebjsCall(msg: Message): { video: boolean; missed: boolean } | undefined {
if ((msg.type as string) !== 'call_log') return undefined;
const d = (msg as unknown as { _data?: { isVideoCall?: boolean; callDuration?: number } })._data ?? {};
return { video: Boolean(d.isVideoCall), missed: !msg.fromMe && !d.callDuration };
}
/**
* The `media` envelope for a message whose blob is not downloaded: keeps the sender-declared metadata
* so the `media` field stays present (n8n/dashboard contract) while carrying the `omitted` marker
* instead of base64. Used when downloads are disabled, the size pre-gate trips, the aggregate history
* budget is spent, or the download fails/times out.
*/
export function declaredOnlyMedia(msg: Message): IncomingMessage['media'] {
const data = (msg as unknown as { _data?: { size?: number; mimetype?: string; filename?: string } })._data;
return {
mimetype: data?.mimetype ?? '',
filename: data?.filename || undefined,
omitted: true,
sizeBytes: coerceDeclaredSize(data?.size),
};
}
/** The media size the sender declared; 0 when unknown, which does not pre-gate the download. */
export function declaredMediaSize(msg: Message): number {
return coerceDeclaredSize((msg as unknown as { _data?: { size?: unknown } })._data?.size);
}
/**
* Whether the adapter's capInboundMediaFor, with no override, downloads this message's media: its
* pre-gates, read as the message arrives so the download can be given room first.
*/
export function plannedInboundDownload(msg: Message): boolean {
return Boolean(msg.hasMedia) && isMediaDownloadEnabled() && declaredMediaSize(msg) <= inboundMediaMaxBytes();
}
/** A media download as {@link downloadMediaInPage} returns it: `data` is empty when the payload was over the cap. */
export interface PageMediaDownload {
mimetype: string;
filename?: string;
data: string;
/** Decrypted byte length, measured in the page. */
sizeBytes: number;
}
/**
* Page-side `Message#downloadMedia()` (whatsapp-web.js 1.34.7) with two changes. It passes `mimetype`
* to `downloadAndMaybeDecrypt()`, which current WhatsApp Web builds require (upstream issue #201908),
* and it checks the decrypted length against `maxBytes`. The size the sender declares is not the size
* WhatsApp serves, and upstream base64-encodes and ships whatever it decrypts, so an understated
* `fileLength` brought an arbitrarily large string over the protocol into Node. An over-cap payload
* comes back with its size and no data. `undefined` and `null` keep upstream's meaning: no usable
* media.
*/
export async function downloadMediaInPage(args: {
msgId: string;
maxBytes: number;
}): Promise<PageMediaDownload | null | undefined> {
type PageMsg = Record<string, unknown> & {
mimetype: string;
filename?: string;
mediaData?: { mediaStage: string };
downloadMedia: (opts: object) => Promise<unknown>;
};
const w = window as unknown as {
require(m: 'WAWebCollections'): {
Msg: {
get: (id: string) => PageMsg | undefined;
getMessagesById: (ids: string[]) => Promise<{ messages?: PageMsg[] } | undefined>;
};
};
require(m: 'WAWebDownloadManager'): {
downloadManager: { downloadAndMaybeDecrypt: (opts: object) => Promise<ArrayBuffer> };
};
WWebJS: { arrayBufferToBase64Async: (buffer: ArrayBuffer) => Promise<string> };
};
const collection = w.require('WAWebCollections').Msg;
const msg = collection.get(args.msgId) || (await collection.getMessagesById([args.msgId]))?.messages?.[0];
// REUPLOADING: the media expired and the phone is re-uploading it; it cannot be downloaded now.
if (!msg || !msg.mediaData || msg.mediaData.mediaStage === 'REUPLOADING') return null;
if (msg.mediaData.mediaStage !== 'RESOLVED') {
await msg.downloadMedia({ downloadEvenIfExpensive: true, rmrReason: 1 });
}
if (msg.mediaData.mediaStage.includes('ERROR') || msg.mediaData.mediaStage === 'FETCHING') return undefined;
try {
const noopQpl = {
addAnnotations() {
return this;
},
addPoint() {
return this;
},
};
const decrypted = await w.require('WAWebDownloadManager').downloadManager.downloadAndMaybeDecrypt({
directPath: msg.directPath,
encFilehash: msg.encFilehash,
filehash: msg.filehash,
mediaKey: msg.mediaKey,
mediaKeyTimestamp: msg.mediaKeyTimestamp,
type: msg.type,
mimetype: msg.mimetype,
signal: new AbortController().signal,
downloadQpl: noopQpl,
});
const meta = { mimetype: msg.mimetype, filename: msg.filename, sizeBytes: decrypted.byteLength };
if (meta.sizeBytes > args.maxBytes) return { ...meta, data: '' };
return { ...meta, data: await w.WWebJS.arrayBufferToBase64Async(decrypted) };
} catch (e) {
if ((e as { status?: number } | null)?.status === 404) return undefined;
// WhatsApp Web's rejection classes are minified, and puppeteer rebuilds a page exception from the class
// name alone (`t: t`). Name the rejection here, with the build it came from, from whatever it carries:
// a name and message, the class and a status, or a bare string.
const thrown = e as
{ name?: string; message?: string; status?: number; constructor?: { name?: string } } | string | null | undefined;
const part = (value: string | number | null | undefined): string =>
value === undefined || value === null ? '' : String(value);
let summary: string;
if (thrown instanceof Object) {
const name = part(thrown.name) || (thrown.constructor === Object ? '' : part(thrown.constructor?.name));
const reason = part(thrown.message) || (thrown.status === undefined ? '' : `status ${part(thrown.status)}`);
summary = name && reason ? `${name}: ${reason}` : name || reason;
} else {
summary = part(thrown);
}
const build = (window as unknown as { Debug?: { VERSION?: unknown } }).Debug?.VERSION;
throw new Error(`${summary || 'unknown rejection'} (WhatsApp Web ${String(build)})`, {
cause: e,
});
}
}
/** Download a message's media through {@link downloadMediaInPage}, on the page that delivered it. */
export async function downloadCappedMedia(
msg: Message,
maxBytes: number,
): Promise<PageMediaDownload | null | undefined> {
const { pupPage } = (
msg as unknown as {
client: { pupPage: { evaluate: <T, A>(fn: (arg: A) => Promise<T>, arg: A) => Promise<T> } };
}
).client;
return pupPage.evaluate(downloadMediaInPage, { msgId: readWid(msg.id) ?? '', maxBytes });
}
/**
* Whether a MediaInput's string `data` is an http(s) URL (to be fetched through the SSRF-guarded
* loadRemoteMedia) rather than base64. Case-insensitive, matching the Baileys adapter — a mixed-case
* scheme like `HTTPS://` must still route through the guarded fetch, not be treated as base64.
*/
export function isHttpUrl(value: string): boolean {
return /^https?:\/\//i.test(value);
}
/**
* Fetch remote media for sending, with an SSRF host guard, a byte cap, and a timeout.
* The guard runs BEFORE any network call, so an internal/reserved URL throws `SsrfBlockedError`
* and no outbound socket is opened. The byte cap (node-fetch `size`) and `AbortSignal` timeout
* bound memory use and hang time. `unsafeMime` is left at its default (false) to preserve the
* existing MIME-detection behavior.
*/
export async function loadRemoteMedia(url: string, sessionProxyUrl: string | undefined): Promise<MessageMedia> {
// Fetch through the SSRF-guarded path: it validates the host, pins a direct or SOCKS connection to
// the vetted IP (so a DNS rebind can't redirect it to an internal target between check and connect;
// an HTTP/HTTPS session proxy resolves the name itself, so nothing is pinned there), caps bytes,
// and refuses redirects. We then build the MessageMedia from the returned bytes — NOT via
// MessageMedia.fromUrl, whose bundled node-fetch performs its own unpinned DNS re-resolution.
// `sessionProxyUrl` routes the fetch through this session's egress proxy (#1626); the browser's
// own requests already ride Chromium's --proxy-server, this one is made by the gateway itself.
const { data, mimetype } = await loadRemoteMediaBuffer(url, sessionProxyUrl);
// The pathname keeps its percent-encoding, and the recipient would see `Laporan%20Bulanan.pdf`. A
// malformed escape keeps the raw name, and a decoded slash is replaced so the label stays one name.
let filename = new URL(url).pathname.split('/').pop() || undefined;
try {
filename = filename && decodeURIComponent(filename).replace(/[/\\]/g, '_');
} catch {
// URIError: keep the raw basename.
}
return new MessageMedia(mimetype || 'application/octet-stream', data.toString('base64'), filename);
}
/**
* True when a send error is WhatsApp Web's "recipient needs a LID we don't have" failure, a bare
* Error its own bundle raises when sending to a `@c.us` for a contact WhatsApp has migrated to
* `@lid`. Matched on WhatsApp Web's error text — there is no structured code; revisit if WhatsApp
* Web changes it.
*/
export function isNoLidForUserError(err: unknown): boolean {
return err instanceof Error && err.message.includes('No LID for user');
}
/**
* True when a send error is the page's "I could not resolve the quoted id" failure, raised only
* because {@link WwebjsMessaging.quoteOptions} opts out of `ignoreQuoteErrors` (Injected/Utils.js:
* 197-198). Matched on the text like {@link isNoLidForUserError} — there is no structured code, and
* puppeteer prefixes its own `Evaluation failed:`, so this is a substring test rather than equality.
*/
export function isQuoteUnresolvedError(err: unknown): boolean {
return err instanceof Error && err.message.includes('Could not get the quoted message');
}
/**
* Build a MessageMedia from a MediaInput (URL → fetched, base64/Buffer → wrapped).
*
* `trustDeclaredType: false` keeps the fetched response's content-type for a remote URL. Use it
* wherever the mimetype is an INSTRUCTION rather than a label: whatsapp-web.js decides how to
* convert a sticker from it, and `Util.formatImageToWebpSticker` returns the media untouched when it
* already says webp. A caller that declares `image/webp` over bytes that are not webp would then
* have raw bytes shipped as a sticker. The response describes bytes the caller never saw, so for
* that one decision it is the better source. The declared filename still wins either way — that is
* a label, and nothing branches on it.
*/
export async function toMessageMedia(
media: MediaInput,
sessionProxyUrl: string | undefined,
opts?: { trustDeclaredType?: boolean; fallbackType?: string },
): Promise<MessageMedia> {
if (typeof media.data === 'string' && isHttpUrl(media.data)) {
const fetched = await loadRemoteMedia(media.data, sessionProxyUrl);
// `loadRemoteMedia` derives both fields from the response (content-type, URL basename) because
// that is all it has. The caller usually knows better, so let an explicit `mimetype`/`filename`
// win — matching `resolveMediaBuffer` on the Baileys adapter, which already prefers the caller's.
// `application/octet-stream` is the DTO's own placeholder, not a statement about the bytes.
if (opts?.trustDeclaredType !== false && media.mimetype && media.mimetype !== 'application/octet-stream') {
fetched.mimetype = media.mimetype;
}
// Sticker path (trustDeclaredType:false): a specific fetched image/video MIME stays authoritative,
// but a generic/empty fetched MIME carries no information, and the caller's declared
// image/* or video/* would otherwise be discarded — whatsapp-web.js then rejects the format
// before running the sticker conversion. Fall back ONLY in that one shape: remote URL +
// trustDeclaredType:false + generic fetched type + convertible declared type. Canonicalize the
// value handed downstream (lowercased, params stripped) so a mixed-case declared type is
// normalized exactly once. A declared image/webp IS accepted here when the fetched response
// carries no usable MIME — the caller is asserting what the bytes actually are, so trusting it
// only in the generic-fetched shape can't bypass the sticker conversion the way globally
// trusting a declared WebP over a specific fetched type would. Arbitrary application/* is
// rejected (e.g. the DTO's own octet-stream placeholder, or application/pdf).
const normalizeMediaType = (value?: string): string => (value ?? '').split(';', 1)[0].trim().toLowerCase();
const fetchedType = normalizeMediaType(fetched.mimetype);
const declaredType = normalizeMediaType(media.mimetype);
const fetchedTypeIsGeneric =
!fetchedType || fetchedType === 'application/octet-stream' || fetchedType === 'binary/octet-stream';
const declaredTypeIsConvertible = declaredType.startsWith('image/') || declaredType.startsWith('video/');
if (opts?.trustDeclaredType === false && fetchedTypeIsGeneric && declaredTypeIsConvertible) {
fetched.mimetype = declaredType;
}
// An image, video or audio route already says what kind of media it carries. When neither the
// caller nor the host says more (the placeholder over an empty or generic response, the S3
// default for an object uploaded without a type), WA Web would classify the bytes from that
// generic type and deliver a photo as a document, so the route's default type stands in.
const declaredTypeIsUnknown = !declaredType || declaredType === 'application/octet-stream';
if (opts?.fallbackType && fetchedTypeIsGeneric && declaredTypeIsUnknown) {
fetched.mimetype = opts.fallbackType;
}
if (media.filename) {
fetched.filename = media.filename;
}
return fetched;
}
const data = typeof media.data === 'string' ? media.data : media.data.toString('base64');
return new MessageMedia(media.mimetype, data, media.filename);
}
/**
* Build the `MessageResult` for a send from whatever whatsapp-web.js hands back.
*
* `client.sendMessage()` can RESOLVE with `undefined` instead of throwing, and it collapses two
* opposite outcomes into that one value (`Client.js:1558`): the chat could not be resolved so nothing
* was sent (`if (!chat) return null`, `Client.js:1539`), or the message went out and only its id could
* not be read back (`Msg.get` miss, `Injected/Utils.js:585`). Nothing here can tell those apart, so an
* absent message is reported as a failed send: a false negative is visible and retryable, while
* claiming delivery for a message that never left is not recoverable. wwebjs's own typings hide the
* case entirely — `index.d.ts` declares `Promise<Message>`, so `strict` never flagged these reads.
*
* A `Message` instance is different: wwebjs only builds one from a real message model, so its presence
* proves the send happened. An id it cannot read there means "sent, id unknown" and carries the empty
* sentinel `forwardMessage` already returns — which `saveOutgoingMessage` stores as NULL rather than a
* fabricated id that a later ack could mis-match.
*/
export function toMessageResult(msg: Message | undefined): MessageResult {
if (!msg) {
throw new Error(
'the engine returned no message for this send, so it may not have been delivered — check the chat before retrying',
);
}
const id = msg.id as unknown as SerializedWid | undefined;
return { id: readWid(id) ?? '', timestamp: msg.timestamp };
}
/**
* whatsapp-web.js drops some sends to a channel or a status/broadcast list before it touches the page
* (`Client.js` sendMessage returns null): a reply, a location or a contact card to any of them, and a
* poll or a sticker to a status or broadcast list. `toMessageResult` can only read that null as a send
* that may have gone out, a 500 the send breaker counts, so refuse it up front with a 501. The
* recipient tests are the library's own, so the two cannot drift. A plain 501, not
* EngineNotSupportedError: the send methods are supported, and that class marks a whole method
* unavailable in the capability matrix.
*/
function ensureSendable(chatId: string, shape: 'reply' | 'location' | 'contact card' | 'poll' | 'sticker'): void {
const channel = /@\w*newsletter\b/.test(chatId);
if (/@\w*broadcast\b/.test(chatId) || (channel && shape !== 'poll' && shape !== 'sticker')) {
const to = channel ? 'a channel' : 'a status or broadcast list';
throw new NotImplementedException(`whatsapp-web.js cannot send a ${shape} to ${to}; nothing was sent.`);
}
}
/**
* Messaging operations extracted from WhatsAppWebJsAdapter: the send paths (with the @c.us -> @lid
* resolution cache), reactions, history, delete and edit. The adapter keeps the public methods as
* thin forwarders and injects the shared host surface (./wwebjs-host) via closures, so the delegate
* never touches lifecycle state directly.
*/
export class WwebjsMessaging {
constructor(private readonly host: WwebjsEngineHost) {}
/** Post-ensureReady client handle; see {@link requireClient} for a teardown that lands in between. */
private client(): Client {
return requireClient(this.host);
}
/** See {@link withPage} for what a dead page answers here. */
private withPage<T>(context: string, op: () => Promise<T>): Promise<T> {
return withPage(this.host, context, op);
}
/**
* A read that runs before a reply or forward has sent anything. When the page died under it, or the
* session went away meanwhile, nothing was sent: report the death, then answer the not-ready 409 a
* send gets everywhere else, not the plain page error the send breaker counts. Any other failure
* rethrows unchanged. Not for the send itself, whose failure leaves the outcome unknown.
*/
private async readBeforeSend<T>(context: string, read: () => Promise<T>): Promise<T> {
try {
return await read();
} catch (error) {
this.host.reportIfPageTransportError(error, context);
this.host.ensureReady();
throw error;
}
}
// Cache of resolved individual recipients: `<phone>@c.us` -> the id `sendMessage` accepts (a
// `<lid>@lid` for a migrated contact, or the confirmed `@c.us` for a non-migrated one). `getNumberId`
// is a rate-limited WhatsApp Web existence probe that also throws intermittently, so caching every
// confirmed resolution keeps ordinary sends from re-probing on each message (#580). A `@lid` is
// stable; a stale entry (a contact that migrates mid-session) self-heals via the retry in
// `sendResolved`.
// Unbounded Map, bounded in practice by distinct recipients per session; add an LRU only if a
// session ever addresses a truly unbounded set of fresh numbers.
private readonly resolvedSendIds = new Map<string, string>();
// The `<phone>@c.us` keys of the cache above whose `@lid` the mapping store has not taken (its write failed):
// the next send reports the pair again, so a failed write costs one more write, not a fresh probe.
private readonly unreportedLids = new Set<string>();
/**
* Resolve an individual (`@c.us`) recipient to the id whatsapp-web.js will accept. WhatsApp has
* migrated some contacts to privacy-id addressing, for which `sendMessage` throws `No LID for user`
* on the phone WID but accepts the `@lid` that `getNumberId` returns (#573). Any server-confirmed
* resolution (a distinct `@lid` OR a confirmed non-migrated `@c.us`) is cached, since it is stable
* and re-probing costs a rate-limited round-trip (#580); a `null`/thrown lookup is NOT cached so an
* unregistered or transiently-flaky contact keeps being retried. Groups/channels and already-`@lid`
* targets are returned unchanged, and any resolution failure falls back to the original id so a send
* is never blocked on it.
*/
async resolveSendId(chatId: string): Promise<string> {
if (!chatId.endsWith('@c.us')) {
return chatId;
}
const cached = this.resolvedSendIds.get(chatId);
if (cached) {
if (this.unreportedLids.delete(chatId)) this.reportLid(chatId, cached);
return cached;
}
try {
const wid = await this.host.getNumberId(chatId);
if (wid) {
this.resolvedSendIds.set(chatId, wid);
if (wid.endsWith('@lid')) this.reportLid(chatId, wid);
return wid;
}
return chatId;
} catch {
return chatId;
}
}
/**
* Persist a learned phone -> lid so the message read-path (resolveJidCandidates) can bridge this contact's
* `@c.us` and `@lid` rows on a pure whatsapp-web.js deployment (#583 R3). Fire-and-forget: resolution (and
* the send) must never block/fail on the write. A write the store reports failed (it resolves false, or
* rejects) is marked for the next send, unless a newer resolution has replaced this one meanwhile.
*/
private reportLid(chatId: string, wid: string): void {
const failed = (): void => {
if (this.resolvedSendIds.get(chatId) === wid) this.unreportedLids.add(chatId);
};
void this.host.config.lidMappingStore
?.remember(userPart(wid), userPart(chatId), this.host.config.sessionId)
?.then(stored => {
if (stored === false) failed();
}, failed);
}
/**
* The send options that attach a quote, or nothing at all when the caller asked for none.
*
* `ignoreQuoteErrors` defaults to TRUE in the library (documented at Client.js:1383, applied at
* :1480): with it left alone an id whatsapp-web.js cannot resolve sends the message ANYWAY,
* unquoted, and reports success. A caller who asked for a reply and received a loose message has
* no signal that anything went wrong, so this opts out and lets the failure surface.
*
* A second, narrower drop is NOT covered by that flag: if the message resolves but `canReplyMsg`
* is false, `quotedMsgOptions` stays empty and the send proceeds unquoted (Injected/Utils.js:
* 187-195). That one is upstream behaviour we cannot switch off from here.
*/
private quoteOptions(quotedMessageId?: string): { quotedMessageId?: string; ignoreQuoteErrors?: boolean } {
return quotedMessageId ? { quotedMessageId, ignoreQuoteErrors: false } : {};
}
/**
* Resolve `chatId` and run `send` against the resolved id. If the send fails with `No LID for user`
* — the signature of a contact whose cached/resolved id is stale (typically a `@c.us` for a contact
* that has since migrated to `@lid`) — drop the mapping, re-resolve once, and retry only if the
* fresh id differs, so a genuinely unreachable recipient surfaces its error instead of looping.
*
* When re-resolution cannot help, the recipient is unreachable rather than stale, and the raw
* `No LID for user` is replaced with {@link RecipientUnreachableError} (400). The bare page-side
* Error carries no status and no recipient, so letting it through produced an opaque 500 for what
* is really a caller-visible fact the gateway already established: `getNumberId` returned null.
*
* `quotedMessageId` gets the same treatment for the same reason. Opting out of `ignoreQuoteErrors`
* makes an id the page cannot resolve throw, but it throws a bare Error, and two things follow from
* that: the caller receives a 500 for an id THEY supplied, where the Baileys adapter answers 404
* (`requireStored`) for the identical request; and `countsTowardSendBreaker` classifies anything
* that is not an HttpException as an account-standing failure, so a caller retrying a stale id
* would trip the send breaker on a fault that is purely their own. Mapping it to
* {@link MessageNotFoundError} (404) settles both — the status matches Baileys and the published
* `docs/06` table, and the breaker exempts it as a 4xx.
*/
private async sendResolved<T>(
chatId: string,
send: (to: string) => Promise<T>,
quotedMessageId?: string,
): Promise<T> {
if (quotedMessageId) ensureSendable(chatId, 'reply');
const to = await this.resolveSendId(chatId);
// The lookup is an await a teardown can land in, and resolveSendId answers a failed lookup with the
// unresolved id. The reply and forward legs send through the Message's own client, which the host's
// readiness check on getClient never sees, so a send must not leave for a closing page from here.
this.host.ensureReady();
try {
return await send(to);
} catch (err) {
// A transport-level failure means the page/browser is gone — report it as a death signal.
// No-op for ordinary send errors; the retry/throw behavior below is unchanged.
this.host.reportIfPageTransportError(err, 'sendMessage');
// Before the LID branch: an unresolvable quote is neither stale-id nor transport, and
// re-resolving the recipient would not make the quoted message appear.
if (quotedMessageId && isQuoteUnresolvedError(err)) {
throw new MessageNotFoundError(quotedMessageId);
}
if (!chatId.endsWith('@c.us') || !isNoLidForUserError(err)) {
throw toCapturedPageError(err);
}
this.resolvedSendIds.delete(chatId);
this.unreportedLids.delete(chatId);
const fresh = await this.resolveSendId(chatId);
// Same gap as above, and before the comparison: a lookup that failed because the session went away
// answers the unresolved id, which would read as an unreachable recipient.
this.host.ensureReady();
if (fresh === to) {
throw new RecipientUnreachableError(chatId);
}
// The first send threw, but wwjs can throw after the message is already on the wire — so this
// retry may produce a duplicate. Log it: without this the second copy is invisible.
this.host.logger.warn('Send retried against a re-resolved id after "No LID for user"; may duplicate', {
chatId,
staleId: to,
freshId: fresh,
});
try {
return await send(fresh);
} catch (retryErr) {
// The page can die during the retry as well; report it exactly as the first attempt does.
this.host.reportIfPageTransportError(retryErr, 'sendMessage');
// Same remap as the first attempt. Re-resolving the RECIPIENT says nothing about the quoted
// message, so a send that reaches the page on the fresh id and only then fails on the quote
// is the same caller fault — without this it would be a 500 on the retry where the identical
// failure on the first attempt was a 404.
if (quotedMessageId && isQuoteUnresolvedError(retryErr)) {
throw new MessageNotFoundError(quotedMessageId);
}
// The re-resolved id is no better than the stale one — same unreachable recipient, and the
// raw error would 500 exactly as the first one did.
if (isNoLidForUserError(retryErr)) {
throw new RecipientUnreachableError(chatId);
}
throw toCapturedPageError(retryErr);
}
}
}
async sendTextMessage(
chatId: string,
text: string,
mentions?: string[],
options?: { linkPreview?: boolean; customPreview?: CustomLinkPreview } & Quotable,
): Promise<MessageResult> {
this.host.ensureReady();
// wwebjs accepts neutral `<phone>@c.us` WIDs directly as mentionedJidList, so no de-normalization
// is needed. Omit the options object entirely when none are given to keep today's send behavior.
//
// Only an explicit `false` is forwarded. whatsapp-web.js reads the flag as
// `linkPreview === false ? undefined : true` (Client.js:1458), so passing `true` is identical to
// passing nothing — sending it anyway would add an options object to every plain send for no
// change in behaviour.
// whatsapp-web.js takes a BOOLEAN only (index.d.ts:1547) — there is no way to hand it title,
// description or a thumbnail. Silently dropping the caller's preview would send a message that
// looks nothing like what they asked for, so it refuses instead.
if (options?.customPreview) {
throw new EngineNotSupportedError('sendTextMessage(customPreview)');
}
const sendOptions: {
mentions?: string[];
linkPreview?: boolean;
quotedMessageId?: string;
ignoreQuoteErrors?: boolean;
} = this.quoteOptions(options?.quotedMessageId);
if (mentions?.length) sendOptions.mentions = mentions;
if (options?.linkPreview === false) sendOptions.linkPreview = false;
const msg = await this.sendResolved(
chatId,
to =>
Object.keys(sendOptions).length
? this.client().sendMessage(to, text, sendOptions)
: this.client().sendMessage(to, text),
options?.quotedMessageId,
);
return toMessageResult(msg);
}
async sendImageMessage(chatId: string, media: MediaInput): Promise<MessageResult> {
return this.sendMediaMessage(chatId, media, undefined, 'image/jpeg');
}
async sendVideoMessage(chatId: string, media: MediaInput): Promise<MessageResult> {
return this.sendMediaMessage(chatId, media, undefined, 'video/mp4');
}
async sendAudioMessage(chatId: string, media: MediaInput): Promise<MessageResult> {
return this.sendMediaMessage(chatId, media, media.ptt ? { sendAudioAsVoice: true } : undefined, 'audio/mpeg');
}
/**
* Without `sendMediaAsDocument` whatsapp-web.js lets WA Web classify the attachment from its declared
* mimetype (`Injected/Utils.js` `processMediaData` -> `prepRawMedia`), so an `image/*`, `video/*` or
* `audio/*` payload posted here reached the recipient as a photo/video/audio bubble — re-encoded and
* stripped of its filename — instead of a document (#989). Baileys has always forced it via the
* explicit `document:` content key, so the two engines disagreed on the same request.
*
* The flag is withheld for `status@broadcast` and broadcast lists: whatsapp-web.js refuses every
* `@broadcast` recipient outright once it is set (`Client.js` returns `null`, which `toMessageResult`
* surfaces as a failed send), so setting it there would turn a working send into an error rather than
* improve it. Those recipients keep the classification they have today.
*/
async sendDocumentMessage(chatId: string, media: MediaInput): Promise<MessageResult> {
const kind = chatKind(chatId);
const asDocument = kind !== 'status' && kind !== 'broadcast';
return this.sendMediaMessage(chatId, media, asDocument ? { sendMediaAsDocument: true } : undefined);
}
private async sendMediaMessage(
chatId: string,
media: MediaInput,
extraOptions?: { sendAudioAsVoice?: boolean; sendMediaAsDocument?: boolean },
fallbackType?: string,
): Promise<MessageResult> {
this.host.ensureReady();
this.host.ensureNotChannelRecipient(chatId);
// Build the media once (a remote URL is fetched here); sendResolved may retry the send itself.
const messageMedia = await toMessageMedia(media, this.host.config.proxy?.url, { fallbackType });
// A nameless document reaches WA Web as `new File([blob], undefined)` and is labelled literally
// "undefined". Only documents render a filename, so default just this path — as Baileys does.
if (extraOptions?.sendMediaAsDocument && !messageMedia.filename) {
messageMedia.filename = 'file';
}
const msg = await this.sendResolved(
chatId,
to =>
this.client().sendMessage(to, messageMedia, {
caption: media.caption,
...(media.mentions?.length ? { mentions: media.mentions } : {}),
// sendAudioAsVoice only for audio, sendMediaAsDocument only for documents;
// {...undefined} contributes no keys.
...extraOptions,
...this.quoteOptions(media.quotedMessageId),
}),
media.quotedMessageId,
);
return toMessageResult(msg);
}
async sendLocationMessage(chatId: string, location: LocationInput): Promise<MessageResult> {
this.host.ensureReady();
ensureSendable(chatId, 'location');
// Import Location class dynamically from whatsapp-web.js
const module = await import('whatsapp-web.js');
const Location = module.Location || module.default?.Location;
const loc = new Location(location.latitude, location.longitude, {
name: location.description || '',
address: location.address || '',
});
const msg = await this.sendResolved(
chatId,
to => this.client().sendMessage(to, loc, this.quoteOptions(location.quotedMessageId)),
location.quotedMessageId,
);
return toMessageResult(msg);
}
async sendContactMessage(chatId: string, contact: ContactCard): Promise<MessageResult> {
this.host.ensureReady();
ensureSendable(chatId, 'contact card');
// Shared builder sanitizes name/number (strips CR/LF, digits-only waid) so a crafted contact
// can't inject extra vCard fields — the previous inline build interpolated raw values.
const vcard = buildVCard(contact);
const msg = await this.sendResolved(
chatId,
to =>
this.client().sendMessage(to, vcard, {
parseVCards: true,
...this.quoteOptions(contact.quotedMessageId),
}),
contact.quotedMessageId,
);
return toMessageResult(msg);
}
async sendStickerMessage(chatId: string, media: MediaInput): Promise<MessageResult> {
this.host.ensureReady();
// Sticker has its own send path (sendMediaAsSticker), not the sendMediaMessage funnel, but it
// hits the same channel crash: for a channel wwjs drops the sticker form and runs processMediaData
// with sendToChannel, which still ends at msg.avParams() (Utils.js:518). Guard it too (#673).
this.host.ensureNotChannelRecipient(chatId);
ensureSendable(chatId, 'sticker');
// Keep the fetched content-type for a remote URL: here the mimetype selects the conversion, and
// whatsapp-web.js returns the media unconverted once it reads as webp (Util.formatImageToWebpSticker).
const messageMedia = await toMessageMedia(media, this.host.config.proxy?.url, { trustDeclaredType: false });
const msg = await this.sendResolved(
chatId,
to =>
this.client().sendMessage(to, messageMedia, {
sendMediaAsSticker: true,
...this.quoteOptions(media.quotedMessageId),
// Same options bag every other media send uses, so the library tags a sticker exactly as it
// tags an image. Omitted when empty to leave an untagged sticker call unchanged.
...(media.mentions?.length ? { mentions: media.mentions } : {}),
}),
media.quotedMessageId,
);
return toMessageResult(msg);
}
async sendPollMessage(chatId: string, poll: PollInput): Promise<MessageResult> {
this.host.ensureReady();
ensureSendable(chatId, 'poll');
// Import Poll dynamically like Location; the .default fallback covers builds where the
// classes land on module.default (a plain `module.Poll` would be undefined there and
// `new Poll` fails with "not a constructor").
const module = await import('whatsapp-web.js');
const Poll = module.Poll || module.default?.Poll;
// wwebjs's typings mark `messageSecret` as required, but at runtime it is optional (it is
// only used as a custom poll id), so cast to the constructor's options type to pass just
// allowMultipleAnswers.
type PollSendOptions = ConstructorParameters<typeof Poll>[2];
const pollOptions = { allowMultipleAnswers: poll.allowMultipleAnswers === true } as PollSendOptions;
const msg = await this.sendResolved(
chatId,
to =>
this.client().sendMessage(
to,
new Poll(poll.name, poll.options, pollOptions),
this.quoteOptions(poll.quotedMessageId),
),
poll.quotedMessageId,
);
return toMessageResult(msg);
}
async replyToMessage(chatId: string, quotedMsgId: string, text: string, mentions?: string[]): Promise<MessageResult> {
this.host.ensureReady();
ensureSendable(chatId, 'reply');
try {
// Find the message to quote
const chat = await this.readBeforeSend('replyToMessage', () => this.client().getChatById(chatId));
if (!chat) {
throw new MessageNotFoundError(quotedMsgId, chatId);
}
const messages = await this.readBeforeSend('replyToMessage', () => chat.fetchMessages({ limit: 100 }));
const quotedMsg = messages.find(m => m.id._serialized === quotedMsgId);
if (!quotedMsg) {
throw new MessageNotFoundError(quotedMsgId);
}
// Reply's send leg hits the same `No LID for user` path as a normal send for a migrated contact,
// so route it through sendResolved (resolve @c.us->@lid, cache, self-heal). reply(content, chatId)
// accepts an explicit target (#583 R1).
// reply(content, chatId, options) takes the same options bag as sendMessage, so a quoted send
// tags participants exactly as a plain one does. The options argument is omitted entirely when
// no tags were asked for, keeping an ordinary reply's call shape untouched (same rule as the
// send path).
const msg = await this.sendResolved(chatId, to =>
mentions?.length ? quotedMsg.reply(text, to, { mentions }) : quotedMsg.reply(text, to),
);
return toMessageResult(msg);
} catch (error) {
this.host.reportIfPageTransportError(error, 'replyToMessage');
throw error;
}
}
async forwardMessage(fromChatId: string, toChatId: string, messageId: string): Promise<MessageResult> {
this.host.ensureReady();
try {
const chat = await this.readBeforeSend('forwardMessage', () => this.client().getChatById(fromChatId));
if (!chat) {
throw new MessageNotFoundError(messageId, fromChatId);
}
const messages = await this.readBeforeSend('forwardMessage', () => chat.fetchMessages({ limit: 100 }));
const msgToForward = messages.find(m => m.id._serialized === messageId);
if (!msgToForward) {
throw new MessageNotFoundError(messageId);
}
// The forward's send leg fails with `No LID for user` for a LID-migrated destination, so resolve
// it (and self-heal a stale mapping) via sendResolved. Capture the id actually sent to so the
// id-recovery below reads back from the SAME (resolved) chat, not the raw @c.us (#583 R1).
// The ids already in that chat are read first, on every attempt, so the recovery below can tell
// the forwarded copy from an earlier send with the same whole-second timestamp. Only messages
// WhatsApp Web already holds are read, so this never pages the chat's history in ahead of the
// send. A read that merely fails never blocks the forward; it only leaves the copy unidentified.
// The newest timestamp it saw is kept too: a concurrent call on the destination chat can page
// older history in before the second read, and those messages are older than every one loaded.
let resolvedTo = toChatId;
let before = undefined as { ids: Set<string>; newest: number } | undefined;
await this.sendResolved(toChatId, async to => {
resolvedTo = to;
before = undefined;
try {
const snapshot = await this.loadedOwnMessages(to);
before = {
ids: new Set(snapshot.map(m => toMessageResult(m).id)),
newest: snapshot.reduce((newest, m) => Math.max(newest, m.timestamp), 0),
};
} catch (error) {
// A page that died under the read is not a read that merely failed. Chromium stopped from
// outside rejects this call before any death listener runs, so report it for the check below,
// but only once the page itself reads gone: a live page whose exception merely says "connection
// closed" is a read that failed, and the forward goes on.
await this.host.reportOnceGone?.(error, 'forwardMessage');
this.host.logger.warn(`Could not read the destination chat before forwarding: ${String(error)}`);
}
// The read above is a page round trip a teardown can land in. Its failure only leaves the copy
// unidentified, unless it shows the page is gone, which this check then refuses.
this.host.ensureReady();
return msgToForward.forward(to);
});
// whatsapp-web.js's forward() returns void, so BEST-EFFORT recover the REAL id of the sent copy by
// reading it back from the destination chat: the one outgoing message that was not there before
// the forward, or, when several appeared, the only one marked forwarded. The delivery-ack matcher
// keys on this id, so a synthetic one would leave the forward stuck at SENT; Baileys already
// returns the real id. The forward already succeeded here, so recovery must NEVER fail the operation.
// When the copy can't be identified (no snapshot, or no single candidate, as with two forwards
// to the same chat at once) we return an explicit-unknown id (empty): message.service then
// leaves the row's waMessageId unset so no ack can mis-match it. A wrong id is worse: persisting
// it merges the forward's row into the other message's.
try {
if (before) {
const known = before;
const fresh = (await this.loadedOwnMessages(resolvedTo)).filter(m => {
const id = toMessageResult(m).id;
return id !== '' && !known.ids.has(id) && m.timestamp >= known.newest;
});
const forwarded = fresh.filter(m => m.isForwarded);
const sent = fresh.length === 1 ? fresh[0] : forwarded.length === 1 ? forwarded[0] : undefined;
if (sent) {
return toMessageResult(sent);
}
}
} catch (error) {
// Still surface a dead page even though the send itself succeeded (detection only; the
// forward's best-effort recovery contract is unchanged).
this.host.reportIfPageTransportError(error, 'forwardMessage');
this.host.logger.warn(`Forward succeeded but recovering the sent message id failed: ${String(error)}`);
}
return { id: '', timestamp: Math.floor(Date.now() / 1000) };
} catch (error) {
this.host.reportIfPageTransportError(error, 'forwardMessage');
throw error;
}
}
/**
* The messages this account sent to a chat that WhatsApp Web already holds, forwarded copy included
* once the send returns. No `limit`: with one, whatsapp-web.js loads earlier history until it has
* that many, which in a chat this account rarely writes to walks the whole history.
*/
private async loadedOwnMessages(chatId: string): Promise<Message[]> {
const chat = await this.client().getChatById(chatId);
return (await chat?.fetchMessages({ fromMe: true })) ?? [];
}
async reactToMessage(chatId: string, messageId: string, emoji: string): Promise<void> {
this.host.ensureReady();
await this.withPage('reactToMessage', async () => {
// NOTE: do NOT resolve chatId to @lid here — whatsapp-web.js reacts using the found message's own
// id, not this chatId, so LID-resolving the lookup gives no send benefit and would miss a message
// stored under the pre-migration @c.us chat (#583).
const chat = await this.client().getChatById(chatId);
// getChatById RESOLVES undefined for an unknown chat (wwebjs does not throw); guard it so the
// caller gets the 404 editMessage returns rather than a TypeError surfacing as an opaque 500.
if (!chat) {
throw new MessageNotFoundError(messageId, chatId);
}
const messages = await chat.fetchMessages({ limit: 100 });
const message = messages.find(m => m.id._serialized === messageId);
if (!message) {
throw new MessageNotFoundError(messageId, chatId);
}
// The message acts through the client that read it, which the host's check on getClient never sees
// again: a teardown that landed in the lookup is the retryable 409, not a write on a closing page.
this.host.ensureReady();
await (message as MessageWithReactions).react(emoji);
});
this.host.logger.debug('Reacted to message', { messageId, emoji: emoji || '(removed)' });
}
async getMessageReactions(chatId: string, messageId: string): Promise<MessageReaction[]> {
this.host.ensureReady();
const reactions = await this.withPage('getMessageReactions', async () => {
const chat = await this.client().getChatById(chatId);
if (!chat) {
throw new MessageNotFoundError(messageId, chatId);
}
const messages = await chat.fetchMessages({ limit: 100 });
const message = messages.find(m => m.id._serialized === messageId);
if (!message) {
throw new MessageNotFoundError(messageId, chatId);
}
const msgWithReactions = message as MessageWithReactions;
return msgWithReactions.hasReaction ? msgWithReactions.getReactions() : [];
});
if (!reactions) {
return [];
}
// Map reactions to our interface format
const result: MessageReaction[] = [];
for (const r of reactions) {
result.push({
emoji: String(r.id),
senders: (r.senders || []).map(s => ({
senderId: String(s.senderId),
emoji: String(s.reaction),
timestamp: Number(s.timestamp),
})),
});
}
return result;
}
async getChatHistory(
chatId: string,
limit: number = 50,
includeMedia: boolean = false,
mediaMaxBytes?: number,
signal?: AbortSignal,
): Promise<IncomingMessage[]> {
this.host.ensureReady();
// Chat.fetchMessages only caps the page when `limit > 0` (Chat.js), so a 0/negative/NaN limit fails
// OPEN and returns every loaded message. Substitute the default, as getChannelMessages does.
const safeLimit = Number.isFinite(limit) && limit >= 1 ? Math.trunc(limit) : 50;
const messages = await this.withPage('getChatHistory', async () => {
const chat = await this.client().getChatById(chatId);
// Unknown chat: getChatById resolves undefined rather than throwing. A chat this account cannot
// see has no history to return, so yield an empty page instead of dereferencing undefined (a
// TypeError that would surface as a 500).
if (!chat) {
return [];
}
return chat.fetchMessages({ limit: safeLimit });
});
const results: IncomingMessage[] = [];
// Aggregate base64 budget across the whole pass: the per-message cap bounds ONE blob, but without
// an aggregate bound a 100-message history could stack ~100 × 50 MiB into one response. Once the
// running total crosses the budget, later media messages get the declared-only `omitted` marker —
// no download — while everything already inlined stays inline (a small history is byte-identical
// to before). `signal` (client disconnect) stops the loop between messages; partials are returned.
// The 25 MiB default is sized for ONE HTTP response and is too tight for a caller that ingests
// into a store instead (mediaMaxBytes — the status seed): two ~10 MiB videos are ~28 MiB of
// base64 and would strip every later status. Such a caller gets a budget derived from its own
// per-item cap rather than an exemption — unbounded here would mean a 50-item seed could stack
// ~650 MiB of base64 on the heap at connect time. The cap is clamped to MEDIA_DOWNLOAD_MAX_BYTES
// first, as capInboundMediaFor clamps each item, so an override above it cannot inflate the budget.
let mediaBudget = !includeMedia
? Number.POSITIVE_INFINITY
: mediaMaxBytes === undefined
? chatHistoryMediaBudgetBytes()
: ingestMediaBudgetBytes(Math.min(mediaMaxBytes, inboundMediaMaxBytes()));
// Sender contacts resolved so far, keyed like Message.getContact() (`author || from`). Each lookup
// is a page round trip and a history page repeats the same few senders, so resolve each once; a
// failed lookup is remembered as undefined rather than retried for every later message.
const senderContacts = new Map<string, MessageContact | undefined>();
for (const msg of messages) {
if (signal?.aborted) {
break;
}
// Reuse the shared mapper so history messages carry the same author/contact
// enrichment as live incoming messages (#223). The mapper defaults chatId to
// msg.from, which is wrong here (history includes fromMe messages whose `from`
// is our own number), so override it to the requested chat and recompute the
// chatId-derived flags (isGroup, isStatusBroadcast, kind) from the real chat.
const out = buildIncomingMessageBase(msg);
out.chatId = chatId;
out.isGroup = chatId.endsWith('@g.us');
out.isStatusBroadcast = chatId === 'status@broadcast';
out.kind = chatKind(chatId);
// buildIncomingMessageBase only fills `contact` from the raw payload's synchronous
// notifyName, which is frequently absent on a history-fetched message object (unlike a
// freshly delivered one). Without this, a group participant not in the account's own
// contacts (author-only, no saved name) shows no sender label at all in the chat view,
// even though the live `message` event handler resolves one via getContact() for the
// exact same message. Mirror that here so history and live rendering agree.
const senderId = msg.author || msg.from;
if (!senderContacts.has(senderId)) {
let resolved: MessageContact | undefined;
try {
const contact = await msg.getContact();
if (contact) resolved = mapContactFields(contact, process.env.WEBHOOK_CONTACT_DETAILS === 'true');
} catch (error) {
this.host.logger.warn(
`Failed to resolve contact for history message ${msg.id._serialized}: ${String(error)}`,
);
}
senderContacts.set(senderId, resolved);
}
const merged = { ...out.contact, ...senderContacts.get(senderId) };
if (Object.keys(merged).length > 0) {
out.contact = merged;
}
const call = extractWwebjsCall(msg);
if (call) out.call = call;
// Mirror the live handler's location + quoted-message enrichment so history renders identically —
// buildIncomingMessageBase sets type='location' but no coordinates, and never resolves quotes.
if (msg.type === MessageTypes.LOCATION && msg.location) {
out.location = {
latitude: Number(msg.location.latitude),
longitude: Number(msg.location.longitude),
description: msg.location.description || undefined,
address: msg.location.address || undefined,
url: msg.location.url || undefined,
};
}
if (msg.hasQuotedMsg) {
try {
const quoted = await msg.getQuotedMessage();
out.quotedMessage = { id: quoted.id._serialized, body: quoted.body };
} catch (error) {
this.host.logger.warn(`Failed to resolve quoted message for ${msg.id._serialized}: ${String(error)}`);
}
}
if (includeMedia && msg.hasMedia) {
if (mediaBudget <= 0) {
out.media = declaredOnlyMedia(msg);
} else {
try {
// Same pre-gate + limiter as live media: a large historical blob shouldn't bloat the
// response/heap. Callers (the status seed) can tighten the cap below the global default.
const capped = await this.host.capInboundMediaFor(msg, mediaMaxBytes);
if (capped) {
out.media = capped;
// Only an inlined payload spends budget; an omitted marker carries no base64.
if (capped.data) {
mediaBudget -= capped.data.length;
}
}
} catch (error) {
this.host.logger.warn(`Failed to download media for ${msg.id._serialized}: ${String(error)}`);
}
}
}
results.push(out);
}
return results;
}
async deleteMessage(chatId: string, messageId: string, forEveryone: boolean = true): Promise<void> {
this.host.ensureReady();
// NOTE: do NOT resolve chatId to @lid here — delete operates on the found message's own key, not
// this chatId, so LID-resolving the lookup gives no benefit and would miss a message stored under
// the pre-migration @c.us chat (#583).
await this.withPage('deleteMessage', async () => {
const chat = await this.client().getChatById(chatId);
if (!chat) {
throw new MessageNotFoundError(messageId, chatId);
}
const messages = await chat.fetchMessages({ limit: 100 });
const message = messages.find(m => m.id._serialized === messageId || m.id.id === messageId);
if (!message) {
throw new MessageNotFoundError(messageId, chatId);
}
this.host.ensureReady();
await message.delete(forEveryone);
});
this.host.logger.debug('Deleted message', { chatId, messageId, forEveryone });
}
async editMessage(chatId: string, messageId: string, body: string, mentions?: string[]): Promise<MessageResult> {
this.host.ensureReady();
// Same lookup window as react/delete: fetchMessages sees only the 100 most recent messages.
// NOTE: do NOT resolve chatId to @lid here — edit operates on the found message's own key, not
// this chatId, so LID-resolving the lookup would miss a message stored under the pre-migration
// @c.us chat (#583).
const edited = await this.withPage('editMessage', async () => {
const chat = await this.client().getChatById(chatId);
// getChatById RESOLVES undefined for an unknown chat (wwebjs does not throw) — that is the same
// client-facing outcome as a message outside the fetch window, not a TypeError (-> 500).
if (!chat) {
throw new MessageNotFoundError(messageId, chatId);
}
const messages = await chat.fetchMessages({ limit: 100 });
const message = messages.find(m => m.id._serialized === messageId || m.id.id === messageId);
if (!message) {
throw new MessageNotFoundError(messageId, chatId);
}
this.host.ensureReady();
// An edit REPLACES the content, so tags are re-applied rather than preserved: omitting mentions
// drops whatever the original carried. Options omitted entirely when none were asked for.
return mentions?.length ? message.edit(body, { mentions }) : message.edit(body);
});
if (!edited) {
// wwebjs RESOLVES null (instead of throwing) when the page-side edit is refused — only the
// account's own text messages are editable; surface the refusal, not a phantom success.
throw new EngineRefusedError(
`the edit of message ${messageId} was rejected — only the account's own text messages can be edited`,
);
}
this.host.logger.debug('Edited message', { chatId, messageId });
return toMessageResult(edited);
}
/**
* Locate a message in the 100-message fetch window shared by react/delete/edit — and now pin.
* Deliberately NOT applied to the existing call sites: they differ in whether they tolerate an
* unknown chat, and rewriting them is not this change's business.
*
* As with those sites, chatId is NOT lid-resolved: the pin acts on the found message's own key,
* so resolving would only risk missing a message stored under the pre-migration @c.us chat.
*
* Readiness is checked again before the message is returned: it acts through the client that read it, so
* a teardown that landed in the lookup would otherwise reach a closing page.
*/
private async findInFetchWindow(chatId: string, messageId: string): Promise<Message> {
const chat = await this.client().getChatById(chatId);
// getChatById RESOLVES undefined for an unknown chat rather than throwing, which is the same
// client-facing outcome as a message outside the window — a 404, not a TypeError-driven 500.
if (!chat) throw new MessageNotFoundError(messageId, chatId);
const messages = await chat.fetchMessages({ limit: 100 });
const message = messages.find(m => m.id._serialized === messageId || m.id.id === messageId);
if (!message) throw new MessageNotFoundError(messageId, chatId);
this.host.ensureReady();
return message;
}
async votePoll(chatId: string, pollMessageId: string, options: string[]): Promise<void> {
this.host.ensureReady();
// Same 100-message window as pin/react/delete, so a poll older than that is unreachable and
// reported as not-found rather than as a failed vote.
try {
await this.withPage('votePoll', async () => {
const message = await this.findInFetchWindow(chatId, pollMessageId);
// vote() matches option TEXTS exactly and silently drops the ones that match nothing. When
// none match it sends an empty selection, the same as `options: []`, which CLEARS the vote
// while the route answered 200. Refuse that case with the poll's real options so a typo or a
// differently-cased text is reported instead of erasing the account's vote. An explicit `[]`
// is still a deliberate clear. A message with no pollOptions is not a poll; vote() below
// rejects it with its own error.
const pollOptions = (message as unknown as { pollOptions?: Array<{ name?: unknown }> }).pollOptions;
if (options.length > 0 && Array.isArray(pollOptions)) {
const names = pollOptions.map(o => o?.name).filter((n): n is string => typeof n === 'string');
if (!options.some(option => names.includes(option))) {
throw new BadRequestException({
statusCode: 400,
error: 'Bad Request',
message: `None of the options match poll ${pollMessageId}; options must be the exact texts: ${names
.map(n => JSON.stringify(n))
.join(', ')}`,
code: 'POLL_OPTION_NOT_FOUND',
validOptions: names,
});
}
}
await (message as unknown as { vote(selected: string[]): Promise<void> }).vote(options);
});
} catch (error) {
// vote() throws a BARE STRING (not an Error) when the target is not a poll creation message
// (Message.js:1010). Left alone that surfaces as an opaque 500; it is a client mistake, so
// map it to a 400. Anything that is a real Error is a genuine engine fault and propagates.
if (typeof error === 'string') {
throw new BadRequestException(`Message ${pollMessageId} is not a poll: ${error}`);
}
throw error;
}
this.host.logger.debug('Voted on poll', { chatId, pollMessageId, options: options.length });
}
async pinMessage(chatId: string, messageId: string, durationSeconds: number): Promise<void> {
this.host.ensureReady();
// The page-side helper returns false rather than throwing for every refusal — a non-number
// duration, a message it cannot resolve, or a send WhatsApp rejected (Injected/Utils.js:1670).
// Surface that as a refusal instead of reporting a pin that never happened.
const pinned = await this.withPage('pinMessage', async () => {
const message = await this.findInFetchWindow(chatId, messageId);
return message.pin(durationSeconds);
});
if (!pinned) {
throw new EngineRefusedError(
`the pin of message ${messageId} was rejected — in a group only admins may pin, and the duration must be 24h, 7d or 30d`,
);
}
this.host.logger.debug('Pinned message', { chatId, messageId, durationSeconds });
}
async starMessage(chatId: string, messageId: string, star: boolean): Promise<void> {
this.host.ensureReady();
// Both resolve void, and the page-side helper silently does nothing when canStarMsg() refuses
// the message (Message.js:672-712). There is no signal to map, so a star that WhatsApp declined
// is indistinguishable from one it accepted — documented rather than faked into a refusal.
await this.withPage('starMessage', async () => {
const message = await this.findInFetchWindow(chatId, messageId);
await (star ? message.star() : message.unstar());
});
this.host.logger.debug(star ? 'Starred message' : 'Unstarred message', { chatId, messageId });
}
async unpinMessage(chatId: string, messageId: string): Promise<void> {
this.host.ensureReady();
// unpin() passes duration 0 itself, so the injected non-number guard cannot bite here; a false
// return means WhatsApp refused the unpin (e.g. not an admin).
const unpinned = await this.withPage('unpinMessage', async () => {
const message = await this.findInFetchWindow(chatId, messageId);
return message.unpin();
});
if (!unpinned) {
throw new EngineRefusedError(`the unpin of message ${messageId} was rejected — in a group only admins may unpin`);
}
this.host.logger.debug('Unpinned message', { chatId, messageId });
}
}