Free, Open Source, Self-Hosted WhatsApp API Gateway
TypeScript apibotgatewayself-hostedwhatsappwhatsapp-apiwhatsapp-automationwhatsapp-botwhatsapp-gatewaywhatsapp-gateway-apiwhatsapp-webwhatsapp-web-api
import { KeyedMutationQueue } from '../../common/utils/keyed-mutation-queue';
import type * as BaileysLib from '@whiskeysockets/baileys';
import type { WACallEvent, WAMessage, WAMessageKey, WASocket } from '@whiskeysockets/baileys';
import {
Contact,
EditedMessage,
EngineEventCallbacks,
EventResponseEvent,
GroupEvent,
IncomingCallEvent,
InboundReceipt,
InboundTicket,
ParticipantPresence,
PresenceState,
CallOutcome,
IncomingMessage,
MessageReceiptEvent,
MessageReceiptStatus,
MessageType,
ReactionEvent,
RevokedMessage,
} from '../interfaces/whatsapp-engine.interface';
import {
BAILEYS_NON_CONTENT_TYPES,
baileysChatJid,
buildIncomingMessageFromBaileys,
extractBaileysBody,
extractBaileysButtonReply,
extractBaileysButtons,
extractBaileysCommerce,
extractBaileysPoll,
extractBaileysContext,
extractBaileysLocation,
isBaileysCatalogShare,
keyParticipant,
mapBaileysEventResponseType,
mapBaileysStatus,
setBaileysText,
} from './baileys-message-mapper';
import { buildEditedMessage } from './message-mapper';
import { toUnixSeconds } from './baileys-history';
import { bytesOf, decryptSecretPayload, messageSecretOf, senderForms, withoutDevice } from './baileys-secret-payload';
import { EngineNotReadyError } from '../../common/errors/engine-not-ready.error';
import { CallNotFoundError } from '../../common/errors/call-not-found.error';
import {
admitInboundSafely,
capInboundMedia,
coerceDeclaredSize,
inboundMediaMaxBytes,
inboundMediaTimeoutMs,
isMediaDownloadEnabled,
runUnderGlobalMediaGate,
withInboundDownloadTimeout,
} from './inbound-media-cap';
import type { Dispatcher } from 'undici';
import type { ConcurrencyLimiter } from '../../common/utils/concurrency-limiter';
import { type createLogger } from '../../common/services/logger.service';
import { createSilentLogger } from './baileys-logger';
import { BAILEYS_QUERY_BUDGET_MS, withQueryDeadline } from './baileys-query-deadline';
import { chatKind, parseWaId, userPart, type ChatKind } from '../identity/wa-id';
/**
* Inbound event handling extracted from BaileysAdapter: the socket event handlers
* (messages/groups/calls), inbound message processing with media capping, and the live-call
* cache behind rejectCall. The adapter rebinds `sock.ev.on(...)` to these handlers and keeps
* `rejectCall` as a thin forwarder (it is a public IWhatsAppEngine method), injecting this
* narrow host surface via closures so the delegate never touches lifecycle state directly.
*/
/**
* The call statuses that mean something to a consumer. Everything else Baileys emits — `ringing`,
* `preaccept`, `transport`, `relaylatency` — is transport chatter, and `terminate` is ambiguous
* (see reportCallOutcome), so neither is mapped.
*/
const CALL_OUTCOMES: Readonly<Partial<Record<string, CallOutcome>>> = {
accept: 'accepted',
reject: 'rejected',
timeout: 'missed',
};
/** The slice of Baileys' PresenceData this adapter reads. */
interface RawPresence {
lastKnownPresence?: PresenceState;
lastSeen?: number;
groupOnlineCount?: number;
}
/**
* The states Baileys can report. Checked rather than trusted: the value crosses a library boundary
* and lands straight in a public webhook payload, so an unknown state added upstream must be dropped
* here rather than published as if this gateway understood it.
*/
const PRESENCE_STATES: ReadonlySet<PresenceState> = new Set<PresenceState>([
'available',
'unavailable',
'composing',
'recording',
'paused',
]);
/**
* The chats a per-recipient receipt is reported for: the two Baileys raises message-receipt.update for, and the
* only ones message.receipt is documented for. A 1:1 chat reports through messages.update instead.
*/
const RECEIPT_CHAT_KINDS: ReadonlySet<ChatKind> = new Set<ChatKind>(['group', 'status']);
/**
* Top-level Message keys that carry no user content. A live message made only of these is dropped;
* messageContextInfo rides along on real content too, so on its own it is not enough to drop.
*/
const PROTOCOL_NOISE_KEYS: ReadonlySet<string> = new Set([
'senderKeyDistributionMessage',
'fastRatchetKeySenderKeyDistributionMessage',
'messageContextInfo',
'messageHistoryNotice',
'messageHistoryBundle',
]);
/**
* Whether two ids provably name different chats or people. Each side is a jid plus the other-dialect
* twin WhatsApp may send beside it (`remoteJidAlt`, `participantAlt`), compared neutralised, so a lid
* the session can resolve matches its phone number. A lid it cannot resolve may still be the phone
* number on the other side, so that pair is never called different, and neither is a side with no id:
* a caller that drops on a mismatch fails open.
*/
export function differentWaIds(
a: ReadonlyArray<string | null | undefined>,
b: ReadonlyArray<string | null | undefined>,
toNeutralJid: (jid: string) => string,
): boolean {
const x = a.filter((j): j is string => !!j).map(toNeutralJid);
const y = b.filter((j): j is string => !!j).map(toNeutralJid);
if (!x.length || !y.length || x.some(j => y.includes(j))) return false;
const lidGap = (p: string[], q: string[]): boolean =>
p.some(j => j.endsWith('@lid')) && !q.some(j => j.endsWith('@lid')) && q.some(j => j.endsWith('@c.us'));
return !lidGap(x, y) && !lidGap(y, x);
}
/**
* Whether the media node Baileys' downloadMediaMessage would fetch is served from WhatsApp's media
* hosts. Baileys builds the address from the message as the sender composed it (`url`, or
* `https://<host of url>` + `directPath`) and fetches it with no host check of its own, so anything
* outside https://*.whatsapp.net on the default port is refused here. The node and the address are
* resolved exactly as rc14's downloadMediaMessage and downloadContentFromMessage resolve them.
*/
export function isWhatsAppMediaSource(
b: Pick<typeof BaileysLib, 'extractMessageContent' | 'getContentType'>,
message: WAMessage['message'],
): boolean {
const content = b.extractMessageContent(message);
const type = content ? b.getContentType(content) : undefined;
const media: unknown = type ? content?.[type] : undefined;
// Baileys refuses a node like this itself, before any fetch.
if (!media || typeof media !== 'object') return true;
const node = media as { url?: string | null; directPath?: string | null; thumbnailDirectPath?: string | null };
const thumbnailOnly = 'thumbnailDirectPath' in media && !('url' in media);
const url = thumbnailOnly ? undefined : node.url;
const directPath = thumbnailOnly ? node.thumbnailDirectPath : node.directPath;
let host = 'mmg.whatsapp.net';
try {
if (url) host = new URL(url).host;
} catch {
// Baileys falls back to its default host for an unparsable url.
}
const target = directPath ? `https://${host}${directPath}` : url;
if (!target) return true;
try {
const parsed = new URL(target);
return (
parsed.protocol === 'https:' &&
parsed.port === '' &&
(parsed.hostname === 'whatsapp.net' || parsed.hostname.endsWith('.whatsapp.net'))
);
} catch {
return false;
}
}
const BAILEYS_MEDIA_TYPES = new Set([
'imageMessage',
'videoMessage',
'ptvMessage',
'audioMessage',
'documentMessage',
'documentWithCaptionMessage',
'stickerMessage',
]);
/** Whether a normalized content type carries a downloadable payload. */
function isBaileysMediaType(contentType: string | undefined): boolean {
return contentType !== undefined && BAILEYS_MEDIA_TYPES.has(contentType);
}
/** The media sub-message of normalized content: its mimetype and declared size. */
function mediaSubMessage(normalized: NonNullable<WAMessage['message']>) {
return (
normalized.imageMessage ??
normalized.videoMessage ??
normalized.ptvMessage ??
normalized.audioMessage ??
normalized.documentMessage ??
normalized.stickerMessage
);
}
export interface BaileysEventsHost {
/** Live socket handle for media re-upload requests (inbound media download). */
getSocket(): WASocket;
/** Raw socket handle, null before connect — rejectCall must tell "not connected" apart from a live socket. */
getSocketOrNull(): WASocket | null;
readonly logger: ReturnType<typeof createLogger>;
toNeutralJid(jid: string): string;
normalizedSelfJid(): string;
/** Lazily loaded @whiskeysockets/baileys module (ESM-only; loaded on first connect, not at boot). */
loadLib(): Promise<typeof BaileysLib>;
/** Session proxy dispatcher for the media download; undefined = direct. */
getFetchDispatcher(): Dispatcher | undefined;
/** The adapter's inbound media download gate (shared so the bound holds across all inbound paths). */
readonly inboundLimiter: ConcurrencyLimiter;
/** Learn any lid->pn pair a message key carries (also writes through to the persistent table). */
recordKeyLidMappings(
key: Pick<WAMessageKey, 'remoteJid' | 'remoteJidAlt' | 'participant' | 'participantAlt' | 'fromMe'>,
): void;
/** Seed the chat's last-message preview + sort time from an inbound message. */
recordMessage(msg: WAMessage, type?: MessageType, order?: number): void;
/** Reserve a message's place in the observed order on arrival, ahead of any limiter, store or media wait. */
nextMessageOrder?(): number;
/** Apply a message edit to the stored body. */
recordMessageEdit(chatId: string, messageId: string, text: string, type?: MessageType): void;
findPersistedLidPhone?(jid: string): Promise<string | null>;
/** Persist an inbound message to the store; undefined when no store is configured. */
putStoredMessage(msg: WAMessage): Promise<void> | undefined;
/** Rewrite a stored message in place (see BaileysMessageStore.update); undefined without a store. */
updateStoredMessage(messageId: string, change: (stored: WAMessage) => WAMessage | null): Promise<void> | undefined;
/**
* True exactly once for the id of a message this session sent through the API, whose library echo
* is arriving; false for anything the session did not send (see OwnSendRegistry).
*/
consumeOwnSend(id: string | null | undefined): boolean;
/** Delete a stored message while `shouldRemove` accepts the copy held then; undefined without a store. */
removeStoredMessage(messageId: string, shouldRemove: (stored: WAMessage) => boolean): Promise<void> | undefined;
/** A message this session already delivered or sent, from the persistent store; undefined without a store. */
getStoredMessage(messageId: string): Promise<WAMessage | null> | undefined;
/** The currently-registered admitInbound callback, if any (assigned at initialize()). */
getAdmitInbound?(): EngineEventCallbacks['admitInbound'];
/** The Baileys module once loaded (it is, before any socket exists), without waiting for it. */
getLoadedLib?(): typeof BaileysLib | undefined;
/** The currently-registered onMessage callback, if any (assigned at initialize()). */
getOnMessage(): EngineEventCallbacks['onMessage'];
/** The currently-registered onMessageCreate callback, if any (assigned at initialize()). */
getOnMessageCreate(): EngineEventCallbacks['onMessageCreate'];
/** The currently-registered onMessageRevoked callback, if any (assigned at initialize()). */
getOnMessageRevoked(): EngineEventCallbacks['onMessageRevoked'];
/** The currently-registered onMessageEdited callback, if any (assigned at initialize()). */
getOnMessageEdited(): EngineEventCallbacks['onMessageEdited'];
/** The currently-registered onMessageReaction callback, if any (assigned at initialize()). */
getOnMessageReaction(): EngineEventCallbacks['onMessageReaction'];
/** The currently-registered onMessageAck callback, if any (assigned at initialize()). */
getOnMessageAck(): EngineEventCallbacks['onMessageAck'];
/** The currently-registered onMessageReceipt callback, if any (assigned at initialize()). */
getOnMessageReceipt(): EngineEventCallbacks['onMessageReceipt'];
/** The currently-registered onGroupEvent callback, if any (assigned at initialize()). */
getOnGroupEvent(): EngineEventCallbacks['onGroupEvent'];
/** The currently-registered onEventResponse callback, if any (assigned at initialize()). */
getOnEventResponse(): EngineEventCallbacks['onEventResponse'];
/** A contact from the session's own store, by any id dialect; no network read. */
findContact(contactId: string): Contact | null;
/** The currently-registered onCall callback, if any (assigned at initialize()). */
getOnCall(): EngineEventCallbacks['onCall'];
/** The currently-registered onPresenceUpdate callback, if any (assigned at initialize()). */
getOnPresenceUpdate(): EngineEventCallbacks['onPresenceUpdate'];
/** The currently-registered onCallOutcome callback, if any (assigned at initialize()). */
getOnCallOutcome(): EngineEventCallbacks['onCallOutcome'];
}
/** The subset of a Baileys `messages.update` entry this adapter reads. */
interface BaileysMessageUpdate {
key?: { id?: string | null; remoteJid?: string | null };
update?: { status?: number | null; eventResponses?: BaileysEventResponse[] | null };
}
/** A decrypted RSVP as Baileys re-emits it under `update.eventResponses`. */
interface BaileysEventResponse {
eventResponseMessageKey?: WAMessageKey | null;
senderTimestampMs?: number | { toNumber(): number } | null;
response?: {
response?: number | null;
timestampMs?: number | { toNumber(): number } | null;
extraGuestCount?: number | null;
} | null;
}
interface LiveCallHandle {
callFrom: string;
expiresAt: number;
from: string;
isVideo: boolean;
isGroup: boolean;
}
/** Every teardown clears the live-call map; counting those clears lets a reject in flight tell that its
* connection was torn down meanwhile. */
class LiveCallMap<V> extends Map<string, V> {
clears = 0;
override clear(): void {
this.clears++;
super.clear();
}
}
/** A rejection awaiting WhatsApp: the handle it took out of the live calls, and the teardowns seen when it began. */
interface CallRejection {
entry: LiveCallHandle;
clears: number;
/** A `terminate` for the call arrived meanwhile: the call is over, whatever the attempt turns out to be. */
ended: boolean;
}
export class BaileysEvents {
/** How long a received call's handle stays rejectable. Calls ring for roughly a minute, so
* two minutes covers the ringing window with margin without pinning dead calls for long. */
private static readonly LIVE_CALL_TTL_MS = 2 * 60_000;
/** Live incoming calls by call id, holding the raw `from` JID sock.rejectCall() needs — the
* call event is long gone by the time a reject arrives, so it must be cached at event time.
* Readonly reference, owned here; the adapter's lifecycle clears it on teardown. */
readonly liveCalls = new LiveCallMap<LiveCallHandle>();
/**
* Calls whose rejection is pending. The handle is out of liveCalls meanwhile, so it cannot be rejected
* twice, yet a signal that ends the call still finds it here and publishes its outcome. A signal that
* publishes an outcome of its own (accept, reject, timeout), a ring of another call under the id and a
* teardown make the rejection stale. A `terminate`, or another tag of the same call, does not: WhatsApp may
* send the terminate that follows our own rejection before it acknowledges it.
*/
private readonly rejections = new Map<string, CallRejection>();
/** How many ids the record of deletes for everyone keeps before it forgets the oldest. */
static readonly DELETED_FOR_EVERYONE_LIMIT = 5_000;
/**
* Inbound messages still being processed, by id, with the key and content of the latest delivery, so
* an edit or delete of one waits for its store write, a delete can be checked against its target
* meanwhile, and an encrypted edit finds the secret of an original that is not stored yet.
*/
private readonly inboundInFlight = new Map<
string,
{ key: WAMessageKey; message: WAMessage['message']; done: Promise<void> }
>();
/**
* Ids of messages deleted for everyone, oldest first. The stored copy is emptied too, but that can
* land late: a delete can overtake the original while it downloads its media, and a repeat delivery
* can be stored after the delete was applied. Whatever the store holds meanwhile, a message named
* here is never quoted, forwarded or reacted to, nor stored with its content. Bounded, because the
* windows it covers close once the original's processing settles, and the store has caught up then.
*/
private readonly deletedForEveryone = new Set<string>();
/**
* The latest edit of a message still being processed, by id, with the key it was sent under. The
* edit is announced first and finds no row or preview to change, and a repeat delivery can be stored
* after the edit was applied, so the original is stored and announced with this text instead, and
* a quote or forward meanwhile carries it too (see pendingEditOf). `afterOtherText` says an earlier
* edit had another text, so one of them changed the text even if this one restores it. Dropped once
* the message's processing settles, and bounded like deletedForEveryone, which wins over it.
*/
private readonly editedWhileInFlight = new Map<
string,
{ envelope: WAMessageKey; body: string; afterOtherText: boolean }
>();
/**
* The deliveries of an id handed to onMessage that have no outcome yet, by id: how many, and a promise
* that settles when the last of them has one (or is let go of after OUTCOME_HOLD_MS). The stored copy
* of such an id may be a duplicate the session is about to call another message's (the real one lives
* in its table only), so it cannot judge a change that reads as foreign to it yet: that change waits
* on `ended` and is judged again (see targetsForeignMessage). A hold begins when the delivery is
* handed on. A change that arrives while the delivery is still being processed (limiter wait, repeat
* check, media download) waits for that processing to end first.
*/
private readonly outcomesPending = new Map<string, { count: number; ended: Promise<void>; free: () => void }>();
/**
* Reactions, edits and deletes that reached a message still being processed where nothing is admitted before
* the emit (SQLite), by its id, in the order they arrived, with the timer that lets them go if the message is
* never handed on. The session holds no entry for such a message until it is emitted, so a reaction announced
* earlier is stored nowhere and an edit leaves no marker: they are announced right after the emit instead (see
* announceWhenHandedOn).
*/
private readonly changesAwaitingEmit = new Map<
string,
{ announce: Array<() => void>; timer: ReturnType<typeof setTimeout> }
>();
/** How many changes wait for a delivery or its outcome (see parkUntil); the rest are judged at once. */
private changesParked = 0;
/**
* How many changes wait in changesAwaitingEmit; the rest are announced at once. Counted apart from the parks,
* so changes waiting for their message cannot make a change that has to wait for an outcome be dropped.
*/
private changesAwaiting = 0;
/** Up to 64 preparations keep per-message order across directory reads; later arrivals wait for room. */
private readonly messageChanges = new KeyedMutationQueue();
private changesPreparing = 0;
private preparationRoom?: { ready: Promise<void>; release: () => void };
private retirePreparations!: () => void;
private preparationsRetired = new Promise<void>(resolve => {
this.retirePreparations = resolve;
});
private static readonly CHANGES_PARKED_LIMIT = 64;
/**
* How many conflicting copies of an id have been removed from the store, oldest id first and bounded
* like deletedForEveryone. A read of the store that was out while one went may have returned that
* copy, which is not what the store holds any more (see targetsForeignMessage). Counted per id: a
* copy removed under another id says nothing of the one a change was judged against.
*/
private readonly copyRemovals = new Map<string, number>();
/** How long an id stays held for the session's outcome; a receipt not settled by then is let go. */
private static readonly OUTCOME_HOLD_MS = 5 * 60_000;
/**
* Bumped by fenceStoredWrites when the account is unlinked. A message stores its copy only while the
* generation it arrived under is current: one still processing when the store is wiped (a media
* download outlives the socket, and the limiter queue is unbounded) must not recreate a row of the
* unlinked account afterwards.
*/
private storeGeneration = 0;
constructor(private readonly host: BaileysEventsHost) {}
getStoredWriteGeneration(): number {
return this.storeGeneration;
}
/** Drop the store writes of every message that arrived before now; call before wiping the store. */
fenceStoredWrites(): void {
this.storeGeneration++;
const retire = this.retirePreparations;
this.preparationsRetired = new Promise<void>(resolve => {
this.retirePreparations = resolve;
});
retire();
}
/** Whether a delete for everyone of this message was accepted (see deletedForEveryone). */
wasDeletedForEveryone(messageId: string): boolean {
return this.deletedForEveryone.has(messageId);
}
/**
* The text of an edit announced while this message is still being processed, when that edit may
* change `target`, the key of the copy about to be quoted or forwarded. The stored copy catches up
* once the processing settles, but a repeat delivery can already be stored with the old text.
*/
pendingEditOf(messageId: string, target: WAMessageKey): string | undefined {
const edit = this.inboundInFlight.has(messageId) ? this.editedWhileInFlight.get(messageId) : undefined;
return edit && this.mayChange(target, edit.envelope, false) ? edit.body : undefined;
}
/** Record an accepted delete for everyone of this message (see deletedForEveryone). */
markDeletedForEveryone(messageId: string): void {
this.deletedForEveryone.add(messageId);
if (this.deletedForEveryone.size > BaileysEvents.DELETED_FOR_EVERYONE_LIMIT) {
const [oldest] = this.deletedForEveryone;
this.deletedForEveryone.delete(oldest);
}
}
/** Apply a history delete to the raw cache without announcing a live message event. */
async applyHistoryRevoke(target: WAMessageKey, envelope: WAMessageKey): Promise<WAMessageKey | undefined> {
if (!target.id) return undefined;
const generation = this.storeGeneration;
const found = await this.readTarget(target.id, 'checking what a history revoke targets');
if (generation !== this.storeGeneration) return undefined;
const original = found?.key ?? target;
const resolve = await this.reportedPhones(original, envelope);
if (generation !== this.storeGeneration) return undefined;
if (!this.mayChange(original, envelope, true, resolve)) return undefined;
if (found) this.markDeletedForEveryone(target.id);
this.changeStoredMessage(target.id, copy =>
this.mayChange(copy.key, envelope, true, resolve) ? { ...copy, message: null } : null,
);
return original;
}
handleMessagesUpsert(event: { messages: WAMessage[]; type: string }): void {
for (const msg of event.messages) {
if (!msg.message || !msg.key?.remoteJid) {
continue; // protocol/empty messages carry no neutral content
}
// A receipt that arrives while this message's own upsert is still in Baileys' event buffer is merged
// into the upsert and raised as no message-receipt.update, which the echo skip below would then drop
// with the rest of the echo.
if (msg.userReceipt?.length) {
this.handleMessageReceiptUpdate(msg.userReceipt.map(receipt => ({ key: msg.key, receipt })));
}
// The same buffer merges a 1:1 delivery or read ack, or a rejection by the server, into the upsert as
// `status` and raises no messages.update. What a message carries before any ack (PENDING on an echo,
// SERVER_ACK on one the phone typed) maps to pending or sent and is not one.
const mergedAck = this.mergedAck(msg);
// Baileys echoes every message this session sends through the API back through this same
// path, tagged 'append', and sendContent() already emits onMessageCreate for those via
// emitOwnSendEcho(). WhatsApp replays what the account typed on its phone while the gateway
// was down through the same tag (`node.attrs.offline ? 'append' : 'notify'` in Baileys'
// messages-recv), and those the session has never seen. Nothing on the batch tells the two
// apart except the id, which the adapter recorded when it sent: skip only what we sent, so
// the echo cannot fire onMessageCreate twice and the phone's outage-window sends still land
// as outgoing messages. Real history never reaches this handler; it arrives on
// messaging-history.set and is captured dispatch-free. A re-delivered message of either
// direction the store already holds is dropped in processInboundMessage: the projector's insert
// oracle dedupes the inbound fan-out but runs after the message:received plugin hook, and it
// does not gate dispatch on the own-send path at all, which is also why the echo is caught here.
//
// Only ids this session SENT are consumed here. Claiming every inbound fromMe id instead, to
// close the window where two deliveries of one id arrive before the first is stored, costs
// more than it buys: a first delivery that reports nothing (a partial decrypt arrives as
// protocol noise and is dropped below) would claim the id, and the decryption-retry delivery
// that carries the real body would then be swallowed as a repeat and the message lost. A
// repeat inside that narrow window is a duplicate, which the webhook idempotency key and the
// insert oracle both absorb; a loss is not recoverable, because Baileys acks the node before
// it emits the upsert.
if (msg.key.fromMe === true && this.host.consumeOwnSend(msg.key.id)) {
// The send returned about 100 ms ago (the buffer holds the upsert that long), so the message
// already has its row, or its entry in the projector.
if (mergedAck) this.handleMessagesUpdate([mergedAck]);
this.host.logger.debug('Skipping the echo of a message this session sent', {
msgId: msg.key.id ?? 'unknown',
type: event.type,
});
continue;
}
// An id names one message of one chat and one sender. A delivery that reuses the id of a message
// still being processed under another chat or sender is not a repeat of it: let through, it would
// take the id first (the row, the stored copy, and the key a delete of the first is judged by).
const firstKey = msg.key.id ? this.inboundInFlight.get(msg.key.id)?.key : undefined;
if (firstKey && this.namesAnotherMessage(firstKey, msg.key)) {
this.host.logger.warn('Dropping a message that reuses the id of one still being processed', {
msgId: msg.key.id ?? 'unknown',
remoteJid: msg.key.remoteJid,
});
continue;
}
// Throttle through the limiter so a burst of media messages can't run unbounded parallel
// downloads (each a full decrypted buffer in heap). Ordering stays correct — the message store
// keeps the newest by timestamp. The queue is unbounded, so a burst parks rather than shedding
// and the message keeps its media either way. Nothing rejects here today: the limiter is never
// closed, and processInboundMessage handles its own failures (a media download that fails emits
// the omitted marker rather than throwing). The catch below is a net for the day something does,
// a closed or bounded limiter, so the message is still emitted rather than lost to an unhandled
// rejection.
const generation = this.storeGeneration;
const order = this.host.nextMessageOrder?.();
// Where the session holds a message until its row is written (PostgreSQL), admit it now, in
// arrival order: its chat's order, and a slot of the session's room when it downloads media.
const ticket = this.admitInbound(msg);
const processed = this.host.inboundLimiter
.run(yieldSlot => this.processInboundMessage(msg, { generation, order, ticket, yieldSlot }))
.catch((error: unknown) => {
// Names the failure rather than calling it "saturated", which used to send operators to look
// at concurrency settings for a problem that was never there. The retry below skips the
// limiter and processInboundMessage handles its own errors, so it cannot reject.
const closed = error instanceof Error && error.message.startsWith('ConcurrencyLimiter closed');
this.host.logger.warn(
closed
? 'Inbound media limiter closed during teardown; emitting message without media'
: 'Inbound media download failed; emitting message without media',
{ msgId: msg.key?.id ?? 'unknown', ...(closed ? {} : { error: String(error) }) },
);
return this.processInboundMessage(msg, { generation, order, skipMedia: true, ticket });
});
// The room stays held until the processing settles too, and a message never emitted drops its turn.
ticket?.holdUntil(processed);
void processed.finally(() => ticket?.drop());
// A message the phone typed is created by that processing, and an ack that reached the projector
// first would find nothing to advance, so it waits until the message was handed on.
if (mergedAck) void processed.then(() => this.handleMessagesUpdate([mergedAck]));
const id = msg.key.id;
if (id) {
// A repeat delivery can arrive while the first is still downloading and finish before it, so
// a change waits for every delivery in flight, not only the latest.
const tracked = {
key: msg.key,
message: msg.message,
done: Promise.all([this.inboundInFlight.get(id)?.done, processed]).then(() => undefined),
};
this.inboundInFlight.set(id, tracked);
void tracked.done.finally(() => {
if (this.inboundInFlight.get(id) !== tracked) return;
this.inboundInFlight.delete(id);
// The edit's store write was chained behind this, so the store carries it (or a newer one) now.
this.editedWhileInFlight.delete(id);
// A change that came in after the message was handed on, while it still counted as in flight.
this.handOverChanges(id);
});
}
}
}
/** The ack Baileys' event buffer merged into the upsert of a message the account sent, as an update. */
private mergedAck(msg: WAMessage): BaileysMessageUpdate | undefined {
if (msg.key.fromMe !== true) return undefined;
const status = mapBaileysStatus(msg.status);
// A delivery or read ack is a 1:1 event (groups and statuses report receipts instead); the server
// rejecting a message is reported for every kind of chat.
const reported =
status === 'failed' ||
((status === 'delivered' || status === 'read') && chatKind(msg.key.remoteJid!) === 'individual');
return reported ? { key: msg.key, update: { status: msg.status } } : undefined;
}
/**
* Whether two keys of one id provably name different messages: another chat, another side of the
* conversation, or (outside the account's own messages) another sender. Fails open, like
* {@link differentWaIds}: ids that cannot be compared are the same message.
*/
private namesAnotherMessage(first: WAMessageKey, key: WAMessageKey): boolean {
const neutral = (jid: string): string => this.host.toNeutralJid(jid);
return (
(first.fromMe === true) !== (key.fromMe === true) ||
differentWaIds([first.remoteJid, first.remoteJidAlt], [key.remoteJid, key.remoteJidAlt], neutral) ||
(key.fromMe !== true &&
differentWaIds([first.participant, first.participantAlt], [key.participant, key.participantAlt], neutral))
);
}
/** Admit a live message (see EngineEventCallbacks.admitInbound); undefined where nothing is held. */
private admitInbound(msg: WAMessage): InboundTicket | undefined {
const admit = this.host.getAdmitInbound?.();
if (!admit) return undefined;
return admitInboundSafely(
() => {
// Learned before the chat id is canonicalized, as processInboundMessage does without a ticket.
this.host.recordKeyLidMappings(msg.key);
const remoteJid = msg.key.remoteJid!;
const behindChat = (remoteJid.endsWith('@g.us') || remoteJid.endsWith('@broadcast')) && msg.key.participant;
return admit({
id: msg.key.id ?? '',
chatId: this.host.toNeutralJid(baileysChatJid(remoteJid, msg.key.participant, msg.key.fromMe === true)),
status: remoteJid === 'status@broadcast',
needsRoom: this.plannedMediaDownload(this.host.getLoadedLib?.(), msg),
fromMe: msg.key.fromMe === true,
// As the mapper sets it, so a change that arrives before the emit is held to the same rule.
...(behindChat ? { author: this.host.toNeutralJid(msg.key.participant!) } : {}),
});
},
error =>
this.host.logger.error(
`Could not admit inbound message ${msg.key.id ?? 'unknown'}; processing it without room for media`,
String(error),
),
);
}
/**
* Whether processing `msg` downloads its media: the gates of {@link resolveInboundMedia}, read before
* the processing starts. True when the module is not loaded yet, which cannot happen once a socket
* delivers messages, so a slot is never missing for a download.
*/
plannedMediaDownload(b: typeof BaileysLib | undefined, msg: WAMessage): boolean {
if (!b) return true;
const ownStatusPost = msg.key.fromMe === true && msg.key.remoteJid === 'status@broadcast';
const normalized = b.normalizeMessageContent(msg.message ?? undefined) ?? msg.message ?? undefined;
return (
isBaileysMediaType(b.getContentType(normalized)) &&
!ownStatusPost &&
isMediaDownloadEnabled() &&
coerceDeclaredSize(mediaSubMessage(normalized ?? {})?.fileLength) <= inboundMediaMaxBytes()
);
}
/** Diagnostic: log a contacts event's size + whether records carry names/lids (and a small sample). */
logContactEvent(
event: string,
records: Array<{
id?: string;
name?: string;
notify?: string;
verifiedName?: string;
lid?: string;
jid?: string;
}> = [],
): void {
const list = records ?? [];
this.host.logger.debug('Baileys contacts event', {
action: 'baileys_contacts',
event,
count: list.length,
withName: list.filter(r => r.name || r.notify || r.verifiedName).length,
withLid: list.filter(r => r.lid).length,
sample: list.slice(0, 3).map(r => ({ id: r.id, name: r.name, notify: r.notify, lid: r.lid, jid: r.jid })),
});
}
private async recordPreviewChange(
chatId: string,
messageId: string,
body: string,
type?: MessageType,
generation = this.storeGeneration,
): Promise<void> {
if (generation !== this.storeGeneration) return;
if (type === undefined) this.host.recordMessageEdit(chatId, messageId, body);
else this.host.recordMessageEdit(chatId, messageId, body, type);
if (parseWaId(chatId).kind === 'lid') {
const phone = await this.host.findPersistedLidPhone?.(chatId).catch(() => null);
if (generation !== this.storeGeneration) return;
if (phone) {
if (type === undefined) this.host.recordMessageEdit(`${phone}@s.whatsapp.net`, messageId, body);
else this.host.recordMessageEdit(`${phone}@s.whatsapp.net`, messageId, body, type);
}
}
}
private async processInboundMessage(
msg: WAMessage,
opts: {
generation: number;
order?: number;
skipMedia?: boolean;
ticket?: InboundTicket;
yieldSlot?: <R>(fn: () => Promise<R>) => Promise<R>;
},
): Promise<void> {
try {
const b = await this.host.loadLib();
if (opts.generation !== this.storeGeneration) return;
const remoteJid = msg.key.remoteJid!;
// The chat the events below report: a received broadcast-list message belongs to its sender's
// chat. Store lookups and the foreign-message checks keep the raw key, which is what is stored.
const chatJid = baileysChatJid(remoteJid, msg.key.participant, msg.key.fromMe === true);
// Learn any lid->pn pair the key carries BEFORE canonicalizing ids below, so a fresh @lid
// sender resolves to its phone in this message and for later contact lookups (#362). The pairs
// also write through to the persistent lid->phone table via addLidMappings. Admission did it already.
if (!opts.ticket) this.host.recordKeyLidMappings(msg.key);
// A live disappearing message (also viewOnce / documentWithCaption / edited) arrives wrapped, so the
// raw `getContentType` returns the OUTER wrapper key (e.g. 'ephemeralMessage') and downstream type/
// body/media/location detection would miss the real inner content. Normalize ONCE so the true inner
// type drives routing here AND mapMessage. The protocol and reaction branches below read the
// normalized content too: a client wraps an edit in `editedMessage`, and `ephemeralMessage` can hold
// a revoke or a reaction just as well, so the raw root does not always carry them.
let normalizedRoot = b.normalizeMessageContent(msg.message ?? undefined) ?? msg.message ?? undefined;
let contentType = b.getContentType(normalizedRoot);
// A contact's edit, and a reaction in some chats, arrive encrypted under the secret of the message
// they change. Read with the stored original's secret, they are handled below as the plain
// protocol or reaction message they stand for; one that cannot be read stays dropped as non-content.
if (contentType === 'secretEncryptedMessage' || contentType === 'encReactionMessage') {
const revealed = await this.revealEncryptedModification(b, msg, normalizedRoot, contentType);
if (revealed) {
normalizedRoot = revealed.content;
contentType = revealed.contentType;
}
}
if (contentType === 'protocolMessage' || contentType === 'reactionMessage') {
const targetId = normalizedRoot?.protocolMessage?.key?.id ?? normalizedRoot?.reactionMessage?.key?.id;
await this.prepareMessageChange(targetId, opts, releasePreparation =>
this.processMessageChange(b, msg, normalizedRoot, contentType, { ...opts, releasePreparation }),
);
return;
}
// --- a vote, a pin, an album header and the like: don't emit onMessage ---
// They only point at another message, so mapped they would reach consumers, in either
// direction, as a bodyless `unknown` message (see BAILEYS_NON_CONTENT_TYPES).
if (contentType && BAILEYS_NON_CONTENT_TYPES.has(contentType)) {
this.host.logger.debug('Dropping a message that carries no content of its own', {
action: 'baileys_drop_non_content',
msgId: msg.key.id,
remoteJid,
contentType,
});
return;
}
// --- contentless protocol traffic: don't emit onMessage ---
// A sender-key distribution (Signal traffic every group participant emits on first write or key
// rotation) or a history-sync notice carries no user content, yet reached consumers as a bodyless
// `unknown` message.received (#1568). Drop only a message made entirely of those keys. Anything
// else without a resolvable content type (a call log, a type newer than the bundled proto, which
// decodes to a lone messageContextInfo) still flows on as `unknown`, as it always has.
//
// Known limit: a type newer than the bundled proto that arrives in the same stanza as its sender's
// key distribution is dropped too. Baileys merges the stanza's decrypted parts into one message
// and protobuf decoding discards unknown fields, so it reads { senderKeyDistributionMessage,
// messageContextInfo }: nothing records which part the context info came from or that a field was
// skipped, and a messageContextInfo field such as messageSecret is not proof of content either,
// since the sending client decides what it carries. It stops once the proto knows the type.
const keys = Object.keys(normalizedRoot ?? {});
if (keys.every(k => PROTOCOL_NOISE_KEYS.has(k)) && keys.some(k => k !== 'messageContextInfo')) {
this.host.logger.debug('Dropping contentless protocol message', {
action: 'baileys_drop_protocol_noise',
msgId: msg.key.id,
remoteJid,
keys,
});
return;
}
// --- Normal message: enrich + emit ---
// A message the store already holds was delivered or sent before: WhatsApp re-delivers a node
// whose ack was lost on a drop, so the second copy has to stop here. Downstream would not catch
// it: the own-send path dispatches message.sent whatever its insert did, and the inbound path
// runs the message:received plugin hook before its insert oracle dedupes. The store is written
// by the inbound path below, just before dispatch, and by the send path, and it survives a
// restart, which the registry consulted in handleMessagesUpsert does not. The read fails open
// (see readStoredMessage).
const storedId = msg.key.id ?? null;
if (storedId !== null && (await this.readStoredMessage(storedId, 'checking for a repeat delivery'))) {
this.host.logger.debug('Skipping a re-delivered message this session already recorded', {
msgId: storedId,
});
return;
}
// The account's own status post reaches the projector and is dropped there: a story is not a
// conversation, so no `message.sent` is emitted for it. Downloading its media first is work
// nothing consumes, and a story is a full-size photo or video. Everything else about the path
// is kept, so the message is still recorded and still guards against a repeat delivery.
const ownStatusPost = msg.key.fromMe === true && remoteJid === 'status@broadcast';
const incoming = await this.mapMessage(msg, contentType, {
skipMediaDownload: opts.skipMedia || ownStatusPost,
ticket: opts.ticket,
yieldSlot: opts.yieldSlot,
});
// Stored before it is announced: whoever hears about this message may act on it at once (a quoted
// reply, a reaction, a read receipt), and the store holds a read of an id until its write lands.
// A message deleted for everyone or edited while it was being processed is stored as the change
// leaves it, and a delete wins over an edit.
const deleted = storedId !== null && this.deletedForEveryone.has(storedId);
const edit = storedId !== null && !deleted ? this.editedWhileInFlight.get(storedId) : undefined;
const editedBody = edit && this.mayChange(msg.key, edit.envelope, false) ? edit.body : undefined;
let toStore = deleted ? { ...msg, message: null } : msg;
if (editedBody !== undefined) {
// A copy, so the edit reaches neither Baileys' object nor anyone else holding it.
toStore = JSON.parse(JSON.stringify(msg, b.BufferJSON.replacer), b.BufferJSON.reviver) as WAMessage;
const content = b.normalizeMessageContent(toStore.message ?? undefined);
if (content) setBaileysText(content, editedBody);
// The session is told of the edit too, with a ticket at once and without one right after the emit, and
// compares it with the text the message arrived with. It is told even when the latest edit restored that
// text after another one: the message was edited all the same, and edits announced before the emit, past
// the changes that wait, left no mark.
if (editedBody !== incoming.body || edit?.afterOtherText) incoming.originalBody = incoming.body;
incoming.body = editedBody;
}
if (opts.generation === this.storeGeneration) {
void this.host.putStoredMessage(toStore)?.catch(err =>
this.host.logger.warn('Failed to persist message to store', {
error: err instanceof Error ? err.message : String(err),
}),
);
}
// Its delete was announced first and found nothing to clear, so announcing the message now, or
// leaving its text as the chat preview, would publish what the sender took back. An edit announced
// first found nothing to change either, so the message carries it here and in the preview. Where
// the projector recorded the delete on the message it holds, the message still goes there, as on
// whatsapp-web.js: it stores the row cleared and announces nothing. A delete it never saw (a
// status post, a history revoke) keeps the message from being emitted at all.
if (!deleted || opts.ticket?.revoked) {
const emit = msg.key.fromMe === true ? this.host.getOnMessageCreate() : this.host.getOnMessage();
// The ticket goes along only where one was issued, so elsewhere the call is unchanged.
const receipt = opts.ticket ? emit?.(incoming, opts.ticket) : emit?.(incoming);
this.watchOutcome(msg.key, receipt);
}
this.host.recordMessage(msg, incoming.type, opts.order);
if (deleted) {
this.host.recordMessageEdit(chatJid, storedId, '', 'revoked');
} else if (editedBody !== undefined && storedId !== null) {
this.host.recordMessageEdit(chatJid, storedId, editedBody);
}
} catch (err) {
this.host.logger.error(
`Unhandled error processing inbound message (id=${msg.key?.id ?? 'unknown'}); dropping`,
err instanceof Error ? err.message : String(err),
);
} finally {
// Emitted by now, or never to be: what waited for this message goes to the session in the same turn, so
// it reaches the message before its row is written.
this.handOverChanges(msg.key?.id);
}
}
/** Preparation runs without a media permit; full-queue waiters provide backpressure without blocking its head. */
private async prepareMessageChange(
messageId: string | null | undefined,
opts: { generation: number; ticket?: InboundTicket; yieldSlot?: <R>(fn: () => Promise<R>) => Promise<R> },
work: (releasePreparation: () => void) => Promise<void>,
): Promise<void> {
if (opts.generation !== this.storeGeneration) return;
const retired = this.preparationsRetired;
if (!messageId) {
if (opts.generation === this.storeGeneration) await work(() => undefined);
return;
}
opts.ticket?.drop();
while (this.changesPreparing >= BaileysEvents.CHANGES_PARKED_LIMIT) {
if (!this.preparationRoom) {
let release!: () => void;
const ready = new Promise<void>(resolve => {
release = resolve;
});
this.preparationRoom = { ready, release };
}
await Promise.race([this.preparationRoom.ready, retired]);
if (opts.generation !== this.storeGeneration) return;
}
this.changesPreparing++;
let finish!: () => void;
let fail!: (error: unknown) => void;
const done = new Promise<void>((resolve, reject) => {
finish = resolve;
fail = reject;
});
let releasePreparation!: () => void;
const released = new Promise<void>(resolve => {
releasePreparation = resolve;
});
this.messageChanges.enqueue(messageId, async () => {
const preparing = (async () => {
if (opts.generation === this.storeGeneration) await work(releasePreparation);
})().then(finish, fail);
try {
await Promise.race([preparing, released, retired]);
} finally {
this.changesPreparing--;
const room = this.preparationRoom;
this.preparationRoom = undefined;
room?.release();
}
});
const settled = Promise.race([done, retired]);
await (opts.yieldSlot ? opts.yieldSlot(() => settled) : settled);
}
private async processMessageChange(
b: typeof BaileysLib,
msg: WAMessage,
normalizedRoot: WAMessage['message'],
contentType: string,
opts: {
generation: number;
ticket?: InboundTicket;
yieldSlot?: <R>(fn: () => Promise<R>) => Promise<R>;
releasePreparation: () => void;
},
): Promise<void> {
const remoteJid = msg.key.remoteJid!;
const protocolType = normalizedRoot?.protocolMessage?.type;
const reaction = contentType === 'reactionMessage';
const revoke = !reaction && protocolType === b.proto.Message.ProtocolMessage.Type.REVOKE;
const edit = !reaction && protocolType === b.proto.Message.ProtocolMessage.Type.MESSAGE_EDIT;
const targetId = normalizedRoot?.protocolMessage?.key?.id ?? normalizedRoot?.reactionMessage?.key?.id;
let parked = false;
const inbound = {
...opts,
releasePreparation: () => {
parked = true;
opts.releasePreparation();
},
};
if (
(reaction || revoke || edit) &&
(await this.targetsForeignMessage(
targetId,
msg.key,
edit || (revoke && !remoteJid.endsWith('@g.us')),
reaction ? 'reaction' : undefined,
inbound,
))
)
return;
if (opts.generation !== this.storeGeneration) return;
const apply = () => this.applyMessageChange(b, msg, normalizedRoot, contentType, opts);
// Waiting for an original must not occupy the preparation queue. Once it answers, take a new
// turn before the remaining directory reads, so mixed change kinds still reach callbacks in order.
if (parked) await this.prepareMessageChange(targetId, { ...opts, ticket: undefined }, apply);
else await apply();
}
private async applyMessageChange(
b: typeof BaileysLib,
msg: WAMessage,
normalizedRoot: WAMessage['message'],
contentType: string,
opts: { generation: number; ticket?: InboundTicket; yieldSlot?: <R>(fn: () => Promise<R>) => Promise<R> },
): Promise<void> {
const remoteJid = msg.key.remoteJid!;
const chatJid = baileysChatJid(remoteJid, msg.key.participant, msg.key.fromMe === true);
// --- protocolMessage REVOKE: don't emit onMessage ---
if (contentType === 'protocolMessage') {
const pm = normalizedRoot?.protocolMessage;
if (pm?.type === b.proto.Message.ProtocolMessage.Type.REVOKE) {
const from = msg.key.fromMe === true ? this.host.normalizedSelfJid() : chatJid;
const to = msg.key.fromMe === true ? chatJid : this.host.normalizedSelfJid();
const revoked: RevokedMessage = {
id: pm.key?.id ?? '',
// The REVOKE protocolMessage's key points at the ORIGINAL deleted message,
// so `id` already IS the original here. Mirror it into `revokedId` so that
// field is the reliable cross-engine handle (wwebjs sets it separately).
revokedId: pm.key?.id ?? undefined,
chatId: this.host.toNeutralJid(chatJid),
from: this.host.toNeutralJid(from),
to: this.host.toNeutralJid(to),
type: 'revoked',
body: '',
timestamp: toUnixSeconds(msg.messageTimestamp),
};
await this.recordPreviewChange(chatJid, revoked.id, '', 'revoked', opts.generation);
if (opts.generation !== this.storeGeneration) return;
// While the target is still being processed, the store change waits for it and lands after
// this delete is announced, and a repeat delivery may already hold the content in the store:
// record the delete now, checked against the target's own key.
const target = this.inboundInFlight.get(revoked.id);
if (target && this.mayChange(target.key, msg.key, true)) {
this.markDeletedForEveryone(revoked.id);
}
// The stored copy keeps its key, so a late re-delivery is still recognised and a delete
// for me can still address it, but loses its content, so nothing can quote or resend it.
const resolveStored = await this.reportedPhones(
(await this.readTarget(revoked.id, 'reading a delete target'))?.key,
msg.key,
);
if (opts.generation !== this.storeGeneration) return;
this.changeStoredMessage(pm.key?.id, stored =>
this.mayChange(stored.key, msg.key, true, resolveStored) ? { ...stored, message: null } : null,
);
// Behind the reactions and edits of the message that wait for its emit, never for the message itself:
// the delete keeps it from being emitted, and they were made before it.
this.announceWhenHandedOn(
revoked.id,
opts.ticket,
() => this.host.getOnMessageRevoked()?.(revoked, { fromMe: msg.key.fromMe === true }),
true,
);
return;
}
if (pm?.type === b.proto.Message.ProtocolMessage.Type.MESSAGE_EDIT) {
// MESSAGE_EDIT wraps the message's latest content. Normalize that INNER content separately
// so captions, type, PTT, media presence and mentions describe the edited value rather than
// the outer protocol envelope.
const normalizedEdited = b.normalizeMessageContent(pm.editedMessage ?? undefined) ?? pm.editedMessage ?? {};
const editedContentType = b.getContentType(normalizedEdited);
const editedSubMessage =
normalizedEdited.extendedTextMessage ??
normalizedEdited.imageMessage ??
normalizedEdited.videoMessage ??
normalizedEdited.audioMessage ??
normalizedEdited.documentMessage ??
normalizedEdited.stickerMessage ??
normalizedEdited.locationMessage;
const contextInfo = editedSubMessage?.contextInfo;
const base = buildIncomingMessageFromBaileys(
{
id: pm.key?.id ?? '',
remoteJid,
fromMe: msg.key.fromMe === true,
participant: keyParticipant(msg.key),
body: extractBaileysBody(normalizedEdited),
contentType: editedContentType,
isPtt: normalizedEdited.audioMessage?.ptt === true,
timestamp: this.toEditUnixSeconds(pm.timestampMs, msg.messageTimestamp),
selfJid: this.host.normalizedSelfJid(),
mentionedJids: contextInfo?.mentionedJid ?? undefined,
},
jid => this.host.toNeutralJid(jid),
);
const hasMedia =
editedContentType === 'imageMessage' ||
editedContentType === 'videoMessage' ||
editedContentType === 'audioMessage' ||
editedContentType === 'documentMessage' ||
editedContentType === 'documentWithCaptionMessage' ||
editedContentType === 'stickerMessage';
const edited: EditedMessage = buildEditedMessage(base, hasMedia);
await this.recordPreviewChange(chatJid, edited.messageId, edited.body, undefined, opts.generation);
if (opts.generation !== this.storeGeneration) return;
const target = this.inboundInFlight.get(edited.messageId);
if (target && this.mayChange(target.key, msg.key, false)) {
const earlier = this.editedWhileInFlight.get(edited.messageId);
const afterOtherText = !!earlier && (earlier.afterOtherText || earlier.body !== edited.body);
this.editedWhileInFlight.delete(edited.messageId); // re-inserted as the newest
this.editedWhileInFlight.set(edited.messageId, { envelope: msg.key, body: edited.body, afterOtherText });
if (this.editedWhileInFlight.size > BaileysEvents.DELETED_FOR_EVERYONE_LIMIT) {
const [oldest] = this.editedWhileInFlight.keys();
this.editedWhileInFlight.delete(oldest);
}
}
const resolveStored = await this.reportedPhones(
(await this.readTarget(edited.messageId, 'reading an edit target'))?.key,
msg.key,
);
if (opts.generation !== this.storeGeneration) return;
this.changeStoredMessage(edited.messageId, stored => {
const content = this.mayChange(stored.key, msg.key, false, resolveStored)
? b.normalizeMessageContent(stored.message ?? undefined)
: undefined;
return content && setBaileysText(content, edited.body) ? stored : null;
});
this.announceWhenHandedOn(edited.messageId, opts.ticket, () => this.host.getOnMessageEdited()?.(edited));
return;
}
// Other protocol messages (ephemeral, history sync, etc.) — skip silently.
return;
}
// --- reactionMessage: don't emit onMessage ---
if (contentType === 'reactionMessage') {
const rm = normalizedRoot?.reactionMessage;
if (opts.generation !== this.storeGeneration) return;
const event: ReactionEvent = {
messageId: rm?.key?.id ?? '',
chatId: this.host.toNeutralJid(chatJid),
reaction: rm?.text ?? '',
// A 1:1 key names the chat partner, not the author: for a reaction the account made from
// its phone (fromMe) the reactor is the account itself. Group and status keys carry the
// author as `participant`, own reactions included, which the edit branch reads the same way.
senderId: this.host.toNeutralJid(
keyParticipant(msg.key) ?? (msg.key.fromMe === true ? this.host.normalizedSelfJid() : remoteJid),
),
};
this.announceWhenHandedOn(rm?.key?.id, opts.ticket, () => this.host.getOnMessageReaction()?.(event));
return;
}
}
/**
* Announce a reaction, an edit or a delete of message `id`. With a ticket the session holds the message from
* its arrival and keeps the change for its row, so it is announced at once. Without one the session knows
* nothing of a message before its emit, so a change that reaches a message still being processed is announced
* right after the emit instead, in the order the changes arrived, when the session holds the message. A delete
* (`behindChangesOnly`) never waits for the message: it waits only behind the changes already waiting, so they
* are announced in the order they arrived. A change waits at most the three media deadlines a change aimed at a
* delivery in flight waits (see targetsForeignMessage), and no more than CHANGES_PARKED_LIMIT wait at once, the
* limit of those changes.
*/
private announceWhenHandedOn(
messageId: string | null | undefined,
ticket: InboundTicket | undefined,
announce: () => void,
behindChangesOnly = false,
): void {
const waiting = messageId && !ticket ? this.changesAwaitingEmit.get(messageId) : undefined;
const waits = !!waiting || (!behindChangesOnly && !ticket && !!messageId && this.inboundInFlight.has(messageId));
if (!messageId || !waits || this.changesAwaiting >= BaileysEvents.CHANGES_PARKED_LIMIT) {
announce();
return;
}
this.changesAwaiting++;
if (waiting) {
waiting.announce.push(announce);
return;
}
const timer = setTimeout(() => this.handOverChanges(messageId), 3 * inboundMediaTimeoutMs());
timer.unref();
this.changesAwaitingEmit.set(messageId, { announce: [announce], timer });
}
/** Announce, in order, what waited for message `id` to be handed on (see announceWhenHandedOn). */
private handOverChanges(messageId: string | null | undefined): void {
const waiting = messageId ? this.changesAwaitingEmit.get(messageId) : undefined;
if (!messageId || !waiting) return;
this.changesAwaitingEmit.delete(messageId);
clearTimeout(waiting.timer);
this.changesAwaiting -= waiting.announce.length;
for (const announce of waiting.announce) {
try {
announce();
} catch (err) {
this.host.logger.warn('Failed to announce a change that waited for its message', {
msgId: messageId,
error: err instanceof Error ? err.message : String(err),
});
}
}
}
/**
* Act on what the session made of a message handed to onMessage, once it says. A delivery that
* reuses the id of a different message the session holds was dropped there as a duplicate, yet its
* copy was stored under that id before the emit, and would stand in for the real message when a
* later edit, delete or reaction of it is judged. Detached: it never delays inbound handling, and
* nothing it does can fail it, whatever the callback returns or rejects with.
*/
private watchOutcome(key: WAMessageKey, receipt: void | InboundReceipt): void {
const id = key.id;
if (!id || !receipt?.settled) return;
// The session holds no entry for a status post, so it judges no change aimed at one: only a message
// it holds can stand in for the stored copy there.
const release = key.remoteJid === 'status@broadcast' ? undefined : this.holdOutcome(id);
void Promise.resolve(receipt.settled)
.then(result => (result?.conflict === true ? this.dropConflictingCopy(key, id) : undefined))
.catch((err: unknown) =>
this.host.logger.warn('Could not act on what the session made of a message', {
msgId: id,
error: err instanceof Error ? err.message : String(err),
}),
)
.finally(() => release?.());
}
/**
* Count a delivery of `id` as awaiting the session's outcome, until the returned function is called
* or OUTCOME_HOLD_MS passes, whichever is first, so a receipt that never settles (a hook that never
* returns) cannot keep the id held for the life of the adapter. Ending twice counts once. The changes
* parked for the id wake once its last delivery's hold has ended.
*/
private holdOutcome(id: string): () => void {
let hold = this.outcomesPending.get(id);
if (!hold) {
let free!: () => void;
const ended = new Promise<void>(resolve => (free = resolve));
hold = { count: 0, ended, free };
this.outcomesPending.set(id, hold);
}
const entry = hold;
entry.count++;
let ended = false;
const end = (): void => {
if (ended) return;
ended = true;
clearTimeout(timer);
if (--entry.count > 0) return;
this.outcomesPending.delete(id);
entry.free();
};
const timer = setTimeout(end, BaileysEvents.OUTCOME_HOLD_MS);
timer.unref();
return end;
}
/**
* Remove the copy a conflicting delivery stored, so the real message's later changes are judged
* against nothing wrong. Only a copy that still carries this delivery's own key goes: the store is
* read when the delete runs, behind every write of the id queued before it. Settles once the delete
* has run, so the id stays held until then; never rejects.
*/
private async dropConflictingCopy(key: WAMessageKey, id: string): Promise<void> {
this.host.logger.warn('Dropping the stored copy of a message that reuses the id of another message', {
msgId: id,
remoteJid: key.remoteJid,
});
try {
await this.host.removeStoredMessage(
id,
stored =>
stored.key?.remoteJid === key.remoteJid &&
keyParticipant(stored.key ?? {}) === keyParticipant(key) &&
(stored.key?.fromMe === true) === (key.fromMe === true),
);
} catch (err) {
this.host.logger.warn('Failed to remove the stored copy of a conflicting message', {
msgId: id,
error: err instanceof Error ? err.message : String(err),
});
}
// Counted even when the removal failed: the session said this delivery is not the message the id names.
const removed = this.removalsOf(id) + 1;
this.copyRemovals.delete(id); // re-inserted as the newest
this.copyRemovals.set(id, removed);
if (this.copyRemovals.size > BaileysEvents.DELETED_FOR_EVERYONE_LIMIT) {
const [oldest] = this.copyRemovals.keys();
this.copyRemovals.delete(oldest);
}
}
/** How many conflicting copies of `id` have been removed (see copyRemovals). */
private removalsOf(id: string): number {
return this.copyRemovals.get(id) ?? 0;
}
/**
* What an edit, revoke or reaction targets: the stored copy, or the one still being processed. The
* in-flight copy is taken BEFORE the store is read, because an original that finishes while the read is
* out has left the map and may have been written after the read began, which would find it in neither.
* `processing` settles once that copy's processing has, and is set only when the copy is the in-flight one.
*/
private async readTarget(
messageId: string,
purpose: string,
): Promise<{ key: WAMessageKey; message: WAMessage['message']; processing?: Promise<void> } | null> {
const processing = this.inboundInFlight.get(messageId);
const stored = await this.readStoredMessage(messageId, purpose);
if (stored) return { key: stored.key, message: stored.message };
const inFlight = processing ?? this.inboundInFlight.get(messageId);
return inFlight ? { key: inFlight.key, message: inFlight.message, processing: inFlight.done } : null;
}
/**
* The stored copy of a message id, or null when the store cannot answer.
*
* Deliberately fail-open: a locked database or a row whose JSON no longer parses must not be read
* as "this was never sent". The caller's only other outcome is the catch above, which drops the
* message outright, and Baileys acks the node before it emits the upsert, so WhatsApp does not
* send it again. A repeat is absorbed where it matters: the webhook carries the same idempotency
* key and the insert oracle holds the row to one. A WebSocket subscriber does see the frame twice,
* which is the price paid here deliberately, because a message nobody ever hears about cannot be
* recovered at all. The persist side of the same store is already written this way.
*/
private async readStoredMessage(messageId: string, purpose: string): Promise<WAMessage | null> {
try {
return (await this.host.getStoredMessage(messageId)) ?? null;
} catch (err) {
this.host.logger.warn(`Could not read the message store while ${purpose}`, {
msgId: messageId,
error: err instanceof Error ? err.message : String(err),
});
return null;
}
}
/**
* Read an edit or a reaction WhatsApp sent encrypted under the secret of the message it changes (see
* baileys-secret-payload.ts). The secret comes from the target's stored copy, or from the copy still
* being processed, and the pair of ids it is keyed by from that target's author and this message's
* sender, so a payload only authenticates when the sender really is who the key says. The result is
* the plain message to route as if it had arrived that way, and every guard of that path applies to
* it: its author and chat are checked against the stored target afterwards. Anything that cannot be
* read (an event edit, no stored target, a payload that does not authenticate) answers undefined and
* stays dropped. Never throws.
*/
private async revealEncryptedModification(
b: typeof BaileysLib,
msg: WAMessage,
content: WAMessage['message'],
contentType: string,
): Promise<
{ content: NonNullable<WAMessage['message']>; contentType: 'protocolMessage' | 'reactionMessage' } | undefined
> {
try {
const isEdit = contentType === 'secretEncryptedMessage';
const encrypted = isEdit ? content?.secretEncryptedMessage : content?.encReactionMessage;
const targetKey = encrypted?.targetMessageKey;
const targetId = targetKey?.id;
const payload = bytesOf(encrypted?.encPayload);
const iv = bytesOf(encrypted?.encIv);
if (!encrypted || !targetKey || !targetId || !payload || !iv) return undefined;
if (isEdit) {
// An edit of an event arrives the same way and is not read here. The enum is a number on a live
// message and its name on one read back from the store.
const type = (encrypted as { secretEncType?: unknown }).secretEncType;
const editType = b.proto.Message.SecretEncryptedMessage.SecretEncType.MESSAGE_EDIT;
if (type !== editType && type !== 'MESSAGE_EDIT') return undefined;
}
const original = await this.readTarget(targetId, 'reading the message an encrypted edit or reaction targets');
const secret = messageSecretOf(original?.message);
if (!original || !secret) {
this.host.logger.debug('Cannot read an encrypted edit or reaction: the message it targets is not stored', {
action: 'baileys_encrypted_unreadable',
msgId: msg.key.id ?? 'unknown',
targetId,
});
return undefined;
}
const user = this.host.getSocketOrNull()?.user;
const own = [user?.id, user?.lid].filter((jid): jid is string => !!jid).map(withoutDevice);
// A lid is also tried as the phone number it maps to: a message written under phone addressing can
// be edited under lid addressing, and the key names each party the way its own client did.
const withPhone = (forms: string[]): string[] =>
forms.flatMap(jid => {
const neutral = jid.endsWith('@lid') ? this.host.toNeutralJid(jid) : '';
return neutral.endsWith('@c.us') ? [jid, `${userPart(neutral)}@s.whatsapp.net`] : [jid];
});
const plaintext = decryptSecretPayload({
kind: isEdit ? 'edit' : 'reaction',
secret,
iv,
payload,
targetId,
targetAuthors: withPhone(senderForms(original.key, own)),
modifiers: withPhone(senderForms(msg.key, own)),
});
if (!plaintext) {
this.host.logger.debug('An encrypted edit or reaction did not authenticate against its target', {
action: 'baileys_encrypted_unauthentic',
msgId: msg.key.id ?? 'unknown',
targetId,
});
return undefined;
}
if (isEdit) {
const protocolMessage = b.proto.Message.decode(plaintext).protocolMessage;
// The decrypted message must name the target the secret was taken from, and be an edit.
if (
protocolMessage?.type !== b.proto.Message.ProtocolMessage.Type.MESSAGE_EDIT ||
protocolMessage.key?.id !== targetId
) {
return undefined;
}
return { content: { protocolMessage }, contentType: 'protocolMessage' };
}
const reaction = b.proto.Message.ReactionMessage.decode(plaintext);
return {
content: { reactionMessage: { key: targetKey, text: reaction.text ?? '' } },
contentType: 'reactionMessage',
};
} catch (error) {
this.host.logger.debug('Could not read an encrypted edit or reaction', {
action: 'baileys_encrypted_failed',
msgId: msg.key.id ?? 'unknown',
error: error instanceof Error ? error.message : String(error),
});
return undefined;
}
}
/**
* Whether an edit, revoke or reaction names a stored message it cannot touch: one in another chat,
* or, with `checkAuthor`, one somebody else sent. WhatsApp clients ignore such a message, but Baileys
* emits it as-is, so a contact who knows an id could rewrite or erase that message. The projector
* judges the stored row it would change as well, by the same rule (see mutationTargetsForeignRow) and
* also for messages older than the store read here; this check keeps the adapter's own handling of the
* event off a message it proves foreign. A message still being processed is checked against the key it
* arrived under. Fails open: with no original at all, or ids that cannot be compared (see
* {@link differentWaIds}), the event goes through as it always has.
*
* The copy a change reads as foreign to may be a duplicate of a message the session holds under
* another chat, which only the session can say once it has stored the message and answered. Such a
* change is not handed on to be judged there, since the adapter acts on it before the session does
* (the preview, the stored copy, the delete record): it waits for the delivery to be processed, and
* then for the answer to its id (see parkUntil), and is judged again. A conflicting copy has been
* removed by then, so the real author's change finds nothing to contradict it, and a copy that stays
* is the message the change is foreign to. One still held when the wait ends is dropped.
*
* A reaction to a message the account sent to a broadcast list is exempt: Baileys files the
* own-device copy under the list jid (`<id>@broadcast`), while each recipient reacts from their 1:1
* chat, so no chat can ever match it. A list message the account received is filed under the list
* jid too, but Baileys shows it in the 1:1 chat with its sender (getChatId in process-message.js), so
* a reaction to it may also come from that sender's chat, whose other-dialect id Baileys puts in
* remoteJidAlt. Edits and revokes stay strict.
*/
private async targetsForeignMessage(
targetId: string | null | undefined,
key: WAMessageKey,
checkAuthor: boolean,
kind?: 'reaction',
inbound?: {
ticket?: InboundTicket;
yieldSlot?: <R>(fn: () => Promise<R>) => Promise<R>;
releasePreparation?: () => void;
},
): Promise<boolean> {
if (!targetId) return false;
// The key a wait was for (the delivery in flight, or the copy the change read as foreign to), and the
// removals of this id counted when it began.
let waitedFor: { key: WAMessageKey; removals: number } | undefined;
// When the wait for the id's hold runs out, however many deliveries hold it in turn.
let heldUntil: number | undefined;
let reread = false;
for (;;) {
const removals = this.removalsOf(targetId);
// A message still being processed has no stored copy yet, but the projector may already hold it
// (PostgreSQL), so its own key is checked instead.
const found = await this.readTarget(targetId, 'checking what an edit, revoke or reaction targets');
// Without a stored copy the key the wait was for stands (a delivery that may never have been stored: no
// store, a failed write; or a copy gone since), unless a conflicting copy went since the wait for it
// began: then that delivery was not the message the id names, and nothing says which one is.
const removedSince = waitedFor !== undefined && this.removalsOf(targetId) !== waitedFor.removals;
const original =
found && !found.processing ? found.key : removedSince ? undefined : (found?.key ?? waitedFor?.key);
if (!original || !this.readsAsForeign(original, key, checkAuthor, kind)) return false;
const processing = found?.processing;
const hold = this.outcomesPending.get(targetId);
if (hold) {
// The session has not said yet whether the delivery that stored this copy is the message it holds
// under the id or a duplicate of another one, so the copy cannot judge the change. Parked until it
// has, when a conflicting copy is gone and the real author's change is judged by what remains. The
// key it was judged by is remembered either way: a copy that is gone by then, wiped or unreadable
// and not removed as a conflict, leaves that key to stand.
waitedFor ??= { key: original, removals };
heldUntil ??= Date.now() + BaileysEvents.OUTCOME_HOLD_MS;
const left = heldUntil - Date.now();
if (left > 0 && (await this.parkUntil(hold.ended, left, inbound))) continue;
} else if (!waitedFor && processing && original.remoteJid !== 'status@broadcast' && original.fromMe !== true) {
// No copy is stored yet, only the key of the delivery being processed, and the real message may be
// one the store never held (the session has it by row), so this key cannot say which of the two the
// change names. Judged again once the delivery has been stored and handed on, which is when the
// hold and the removal of a conflicting copy answer it. Only a delivery the session reports on
// counts: a status post is held by no entry there, and an own send gets no receipt.
waitedFor = { key: original, removals };
if (await this.parkUntil(processing, 3 * inboundMediaTimeoutMs(), inbound)) continue;
}
// A conflicting copy went while the store was read, and the read may have returned it: it ends the
// hold only once removed, so the read is the one that can no longer be told from the real copy. Read
// again, with the copy gone, rather than drop the real author's change against it.
if (!reread && this.removalsOf(targetId) !== removals) {
reread = true;
continue;
}
this.host.logger.warn('Dropping an edit, revoke or reaction aimed at a message from another chat or author', {
msgId: key.id ?? 'unknown',
targetId,
remoteJid: key.remoteJid,
});
return true;
}
}
/**
* Park a change until `until` settles or `limitMs` passes, whichever is first: a delivery's processing
* (at most three media download deadlines: a wait for room in the session, then the download) or the
* hold on an id's outcome. Never more than CHANGES_PARKED_LIMIT changes at once. Resolves true once it
* did wait, false when it was not parked.
* A parked change holds nothing the delivery needs. It gives up its inbound slot, which the delivery
* may have to take back after waiting for room, and its place in its chat's order, which a change
* never uses (it is not announced as a message), so it neither starves the delivery nor holds back the
* messages that follow it in the chat.
*/
private async parkUntil(
until: Promise<void>,
limitMs: number,
inbound?: {
ticket?: InboundTicket;
yieldSlot?: <R>(fn: () => Promise<R>) => Promise<R>;
releasePreparation?: () => void;
},
): Promise<boolean> {
if (this.changesParked >= BaileysEvents.CHANGES_PARKED_LIMIT) return false;
this.changesParked++;
try {
inbound?.releasePreparation?.();
if (!inbound?.releasePreparation) inbound?.ticket?.drop();
const wait = (): Promise<void> =>
new Promise<void>(resolve => {
let wake: (() => void) | null = resolve;
// Whichever comes first; the reaction left on a promise that never settles holds nothing.
const end = (): void => {
clearTimeout(timer);
wake?.();
wake = null;
};
const timer = setTimeout(end, limitMs);
timer.unref();
until.then(end, end);
});
await (inbound?.yieldSlot ? inbound.yieldSlot(wait) : wait());
return true;
} finally {
this.changesParked--;
}
}
/** Whether a change arriving under `key` names a message other than the one `original` is. */
private readsAsForeign(original: WAMessageKey, key: WAMessageKey, checkAuthor: boolean, kind?: 'reaction'): boolean {
const broadcast = kind === 'reaction' && !!original.remoteJid?.endsWith('@broadcast');
if (broadcast && original.fromMe === true) return false;
const originalChats = [original.remoteJid, original.remoteJidAlt];
if (broadcast && original.remoteJid !== 'status@broadcast') originalChats.push(original.participant);
const neutral = (jid: string): string => this.host.toNeutralJid(jid);
return (
differentWaIds(originalChats, [key.remoteJid, key.remoteJidAlt], neutral) ||
(checkAuthor &&
((original.fromMe === true) !== (key.fromMe === true) ||
(key.fromMe !== true &&
differentWaIds(
[original.participant, original.participantAlt],
[key.participant, key.participantAlt],
neutral,
))))
);
}
/**
* Apply an edit or a delete for everyone to the stored copy of the message it targets, which is
* what a later quote or forward reads and what a retry resend falls back to. WhatsApp delivers the
* change after the message, but the message can still be downloading its media, or waiting for a
* limiter slot, when the change is processed, and a change written first would be overwritten by
* the original. So the write waits for the original's own processing, which has called put() by
* the time it settles, and the store queues the change behind that put. With nothing in flight the
* change reaches the store at once: this is called before the change is announced, so a read by
* whoever hears of it waits for the write, as a read of a just-announced message waits for its put.
* Detached and best-effort, like the put.
*/
private changeStoredMessage(
messageId: string | null | undefined,
change: (stored: WAMessage) => WAMessage | null,
): void {
if (!messageId) return;
const generation = this.storeGeneration;
const apply = async (): Promise<void> => {
if (generation !== this.storeGeneration) return;
await this.host.updateStoredMessage(messageId, stored =>
generation === this.storeGeneration ? change(stored) : null,
);
};
const inFlight = this.inboundInFlight.get(messageId)?.done;
void (inFlight ? inFlight.then(apply) : apply()).catch(err =>
this.host.logger.warn('Failed to apply an edit or delete to the message store', {
msgId: messageId,
error: err instanceof Error ? err.message : String(err),
}),
);
}
/**
* Whether an edit or delete sent under `envelope` may change the stored message `target`. Baileys
* checks neither the chat nor the sender of either (Utils/process-message.js), so the stored copy
* changes only for one from the same chat and from the message's author. A group admin may delete
* anyone's message, which nothing here can verify, so a group delete skips the author check.
* Compare raw identities and incoming alt pairs. A stored LID/phone pair matches only through a
* reported directory lookup; own-message senderAlt is not proof of the recipient's phone.
*/
private async reportedPhones(...keys: Array<WAMessageKey | undefined>): Promise<(jid: string) => string | null> {
const lids = new Set(
keys
.flatMap(key => [key?.remoteJid, key?.participant])
.filter((jid): jid is string => !!jid && parseWaId(jid).kind === 'lid'),
);
const pairs = new Map<string, string>();
await Promise.all(
[...lids].map(async lid => {
const phone = await this.host.findPersistedLidPhone?.(lid).catch(() => null);
if (phone) pairs.set(userPart(lid), phone);
}),
);
return jid => pairs.get(userPart(jid)) ?? null;
}
private mayChange(
target: WAMessageKey,
envelope: WAMessageKey,
isDelete: boolean,
resolve?: (jid: string) => string | null,
): boolean {
const neutral = (jids: Array<string | null | undefined>): string[] =>
jids.filter((jid): jid is string => !!jid).map(jid => this.host.toNeutralJid(jid));
const chat = (key: WAMessageKey): string[] => neutral([key.remoteJid, key.fromMe ? undefined : key.remoteJidAlt]);
const author = (key: WAMessageKey): string[] =>
key.fromMe === true ? ['fromMe'] : key.participant ? neutral([key.participant, key.participantAlt]) : chat(key);
const overlap = (a: string[], b: string[]): boolean => {
if (parseWaId(a[0] ?? '').kind === 'lid' && parseWaId(b[0] ?? '').kind === 'lid' && a[0] !== b[0]) return false;
return a.some(left =>
b.some(right => {
if (left === right) return true;
const l = parseWaId(left).kind;
const r = parseWaId(right).kind;
return (
(l === 'lid' && r === 'user' && resolve?.(left) === userPart(right)) ||
(r === 'lid' && l === 'user' && resolve?.(right) === userPart(left))
);
}),
);
};
if (!overlap(chat(target), chat(envelope))) return false;
const inGroup = chat(target).some(jid => parseWaId(jid).kind === 'group');
return (isDelete && inGroup) || overlap(author(target), author(envelope));
}
handleMessagesUpdate(updates: BaileysMessageUpdate[]): void {
for (const u of updates) {
const status = mapBaileysStatus(u.update?.status);
if (status && u.key?.id) {
// Canonicalize the update's chat exactly as the inbound mapper does, so an ack's chatId
// matches the chatId of the message events it accompanies.
const chatId = u.key.remoteJid ? this.host.toNeutralJid(u.key.remoteJid) : undefined;
this.host.getOnMessageAck()?.(u.key.id, status, chatId);
}
for (const rsvp of u.update?.eventResponses ?? []) {
void this.emitEventResponse(u.key, rsvp).catch(err =>
this.host.logger.warn('Failed to report an event response', {
msgId: u.key?.id,
error: err instanceof Error ? err.message : String(err),
}),
);
}
}
}
/**
* Baileys `message-receipt.update`: per-participant receipts, which Baileys raises only for group
* and status messages (1:1 receipts arrive as `messages.update` instead). Only receipts for
* messages this account sent are reported, and only for those two chat kinds whichever way the list
* reached this handler; receipts from the account's own linked devices are dropped. The event
* buffer can merge several receipts of one participant into one entry, so each timestamp the entry
* carries becomes its own event. rc14 files a `played` receipt under `readTimestamp`, so on that
* version a voice note that was played reports `read`.
*/
handleMessageReceiptUpdate(
updates: Array<{
key?: { id?: string | null; remoteJid?: string | null; fromMe?: boolean | null };
receipt?: {
userJid?: string | null;
receiptTimestamp?: number | { toNumber(): number } | null;
readTimestamp?: number | { toNumber(): number } | null;
playedTimestamp?: number | { toNumber(): number } | null;
};
}>,
): void {
const onReceipt = this.host.getOnMessageReceipt();
if (!onReceipt) {
return;
}
const isSelf = this.selfMatcher();
for (const { key, receipt } of Array.isArray(updates) ? updates : []) {
if (
!key?.id ||
!key.remoteJid ||
key.fromMe !== true ||
!RECEIPT_CHAT_KINDS.has(chatKind(key.remoteJid)) ||
!receipt?.userJid ||
isSelf(receipt.userJid)
) {
continue;
}
const stamps: Array<[MessageReceiptStatus, typeof receipt.receiptTimestamp]> = [
['delivered', receipt.receiptTimestamp],
['read', receipt.readTimestamp],
['played', receipt.playedTimestamp],
];
for (const [status, ts] of stamps) {
if (ts == null) continue;
const event: MessageReceiptEvent = {
messageId: key.id,
chatId: this.host.toNeutralJid(key.remoteJid),
participant: this.host.toNeutralJid(receipt.userJid),
status,
timestamp: toUnixSeconds(ts),
};
onReceipt(event);
}
}
}
/**
* Matches any jid of this account, in either dialect and from any of its devices (user parts are
* compared). Answers false for everything while the account's own id is unknown.
*/
private selfMatcher(): (jid: string | null | undefined) => boolean {
const selfJid = this.host.normalizedSelfJid();
if (!selfJid) {
return () => false;
}
const phone = userPart(selfJid);
const lid = this.host.getSocketOrNull()?.user?.lid;
const lidUser = lid ? userPart(lid) : undefined;
return (jid: string | null | undefined): boolean => {
if (!jid) return false;
const { kind, userPart: user } = parseWaId(jid);
if (kind === 'user') return user === phone;
if (kind !== 'lid') return false;
if (lidUser !== undefined) return user === lidUser;
// Creds carrying no `user.lid` leave nothing to compare a lid-addressed jid against, and every
// such comparison would answer false. Fall back to the session's own lid to phone mapping,
// which the store learns from the same traffic.
return userPart(this.host.toNeutralJid(jid)) === phone;
};
}
/**
* An RSVP to a WhatsApp event. Baileys decrypts it itself while processing the inbound
* `encEventResponseMessage` (whose upsert the live path drops as non-content): it reads the event
* creation message's `messageSecret` through the socket's getMessage, which this adapter backs
* with the message store, and re-emits the plaintext as a `messages.update` of the CREATION
* message's key. An RSVP to an event the store does not hold cannot be decrypted and never
* arrives here. Decryption authenticates the responder, since the key is derived from their jid.
*/
private async emitEventResponse(eventKey: BaileysMessageUpdate['key'], rsvp: BaileysEventResponse): Promise<void> {
const callback = this.host.getOnEventResponse();
const envelope = rsvp.eventResponseMessageKey;
if (!callback || !eventKey?.id || !eventKey.remoteJid || !envelope?.id) return;
// Learned before any id below is canonicalized, as an inbound message does, so a guest answering
// for the first time is not reported by lid once and by phone number afterwards.
this.host.recordKeyLidMappings(envelope);
// Baileys decrypts an RSVP against whichever stored event its creation key names and compares no
// chats, so a member of two groups can answer in one an event posted in the other. The answer is
// reported for the chat it arrived in, so one sent outside its event's chat is dropped, as an edit,
// revoke or reaction aimed at a message of another chat is. Fails open like those: a store that
// cannot be read, or ids that cannot be compared, report the RSVP as before.
const stored = await this.readStoredMessage(eventKey.id, 'reading the event an RSVP answers');
if (
stored &&
differentWaIds(
[stored.key.remoteJid, stored.key.remoteJidAlt],
[envelope.remoteJid, envelope.remoteJidAlt],
jid => this.host.toNeutralJid(jid),
)
) {
this.host.logger.warn('Dropping an event response sent in a chat other than its event', {
msgId: eventKey.id,
responseMessageId: envelope.id,
remoteJid: envelope.remoteJid,
});
return;
}
const fromMe = envelope.fromMe === true;
// The creation key is the guest's view of the event (in a 1:1 chat its remoteJid is this
// account), so the chat comes from the RSVP's own key, which Baileys has put on our side.
const chatJid = envelope.remoteJid ?? eventKey.remoteJid;
// Same rule as a reaction: a 1:1 key names the chat partner, so the account's own answer is
// attributed to the account; group keys carry the responder as `participant`.
const responder = keyParticipant(envelope) ?? (fromMe ? this.host.normalizedSelfJid() : chatJid);
if (!responder) return;
const event: EventResponseEvent = {
eventMessageId: eventKey.id,
chatId: this.host.toNeutralJid(chatJid),
responderId: this.host.toNeutralJid(responder),
fromMe,
response: mapBaileysEventResponseType(rsvp.response?.response),
responseMessageId: envelope.id,
timestamp: this.toEditUnixSeconds(
rsvp.senderTimestampMs ?? rsvp.response?.timestampMs,
Math.floor(Date.now() / 1000),
),
};
const guests = rsvp.response?.extraGuestCount;
if (typeof guests === 'number' && Number.isFinite(guests)) event.extraGuestCount = guests;
// Named from the session's own contact store, like the sender of message.received, so an
// attendance list can be built from the RSVPs alone without a network read per answer.
const known = this.host.findContact(responder);
if (known?.name || known?.pushName) {
event.contact = {
...(known.name ? { name: known.name } : {}),
...(known.pushName ? { pushName: known.pushName } : {}),
};
}
if (stored?.message) {
const b = await this.host.loadLib();
const name = b.normalizeMessageContent(stored.message)?.eventMessage?.name;
if (name) event.eventName = name;
}
callback(event);
}
/**
* Baileys `group-participants.update`: a membership change. Only add/remove map to the neutral
* join/leave kinds — promote/demote (and 'modify', a phone-number-change rewrite) change no
* membership and are skipped. The event carries no timestamp, so it is stamped at receipt.
*/
handleGroupParticipantsUpdate(event: {
id?: string;
author?: string;
authorPn?: string;
participants?: unknown[];
action?: string;
}): void {
const kind = event.action === 'add' ? 'join' : event.action === 'remove' ? 'leave' : undefined;
if (!kind || !event.id) {
return;
}
const participantIds = (Array.isArray(event.participants) ? event.participants : [])
.map(entry => this.toNeutralGroupParticipantId(entry))
.filter((jid): jid is string => jid !== null);
const payload: GroupEvent = {
kind,
groupId: this.host.toNeutralJid(event.id),
participantIds,
timestamp: Math.floor(Date.now() / 1000),
};
// authorPn is the phone-dialect twin of a lid author: prefer it so the neutral actor id does
// not depend on whether the lid->pn mapping happens to be learned yet.
const actor = event.authorPn ?? event.author;
if (actor) {
payload.actorId = this.host.toNeutralJid(actor);
}
this.host.getOnGroupEvent()?.(payload);
}
/**
* Baileys `groups.upsert`: this session was added to or joined a group. Baileys turns the w:gp2
* `create` notification into this event and a content-less GROUP_CREATE stub, never into
* `group-participants.update`. It drops the notification's type and reason, so a new group, an add
* to an existing group and an invite-link join all arrive alike. Each entry is reported as a join of
* this session's own id through the participants path, which owns the id guard, the authorPn
* preference and the receipt timestamp. The entry lists the whole group, so members added with the
* session are not reported.
*/
handleGroupsUpsert(
groups: Array<{ id?: string; author?: string; authorPn?: string; owner?: string; ownerPn?: string }>,
): void {
const selfJid = this.host.normalizedSelfJid();
if (!selfJid) {
return; // no own id to report as the joining participant
}
// Without the lid fallback inside selfMatcher, a group this session created by a lid-addressed
// actor would be reported as a join of itself.
const isSelf = this.selfMatcher();
for (const group of Array.isArray(groups) ? groups : []) {
// Live, whatsapp-web.js emits no group.join when the session created the group, so that entry is
// skipped. The acting participant alone does not identify it: an invite-link join may name the
// joining session there, so the session must also be the group's owner.
if (
!group ||
((isSelf(group.authorPn) || isSelf(group.author)) && (isSelf(group.ownerPn) || isSelf(group.owner)))
) {
continue;
}
this.handleGroupParticipantsUpdate({
id: group.id,
author: group.author,
authorPn: group.authorPn,
action: 'add',
participants: [selfJid],
});
}
}
/**
* Baileys `group.join-request`: someone asked to join a group the account admins (join-approval
* on). Only action 'created' maps to the neutral join_request kind — the wwebjs event has no
* revoke/reject counterpart, so only the shared signal is surfaced. Upstream scope caveat: rc14
* emits this event only from the NON_ADMIN_ADD stub (172); the direct self-request stub (144) is
* unhandled with an upstream TODO (Utils/process-message.js:569), so an invite-link self-request
* may produce no event on this engine — the REST list endpoint still sees it. The pn twins are
* preferred over lids for the same reason as everywhere else. The event carries no timestamp, so
* it is stamped at receipt.
*/
handleGroupJoinRequest(event: {
id?: string;
author?: string;
authorPn?: string;
participant?: string;
participantPn?: string;
action?: string;
method?: string;
}): void {
if (event.action !== 'created' || !event.id) {
return;
}
const participant = event.participantPn ?? event.participant;
if (!participant) {
return; // nothing addressable to report
}
const payload: GroupEvent = {
kind: 'join_request',
groupId: this.host.toNeutralJid(event.id),
participantIds: [this.host.toNeutralJid(participant)],
timestamp: Math.floor(Date.now() / 1000),
};
const actor = event.authorPn ?? event.author;
if (actor) {
payload.actorId = this.host.toNeutralJid(actor);
}
this.host.getOnGroupEvent()?.(payload);
}
/**
* Baileys `groups.update`: partial group metadata. Each entry becomes one neutral 'update'
* GroupEvent with `changes` filled from whichever of subject/desc/announce/restrict it carries
* (desc → description, restrict → locked). Entries about fields the neutral shape does not model
* (inviteCode, memberAddMode, joinApprovalMode, ...) still emit with empty changes — parity with
* the wwebjs adapter, which emits uninterpretable updates the same way rather than dropping them.
*
* The same event also carries FULL metadata snapshots: groupFetchAllParticipating() emits its
* entire result set through it (Socket/groups.js:56 `sock.ev.emit('groups.update', ...)`), and
* this adapter calls that on every connect (hydrateNames) and every REST getGroups(). Real deltas
* (Utils/process-message.js emitGroupUpdate) carry only `{id, ...oneChangedField, author?}`;
* snapshots are recognized by their full-metadata markers (participants/creation/subjectTime/
* owner/size) and skipped — otherwise every reconnect / GET /groups would flood consumers with
* bogus group.update webhooks whose `changes` were fabricated from the snapshot.
*/
handleGroupsUpdate(
updates: Array<{
id?: string;
subject?: string;
desc?: string;
announce?: boolean;
restrict?: boolean;
author?: string;
authorPn?: string;
// Full-snapshot markers (extractGroupMetadata); the values are unused — presence is the signal.
participants?: unknown;
creation?: unknown;
subjectTime?: unknown;
owner?: unknown;
size?: unknown;
}>,
): void {
for (const update of Array.isArray(updates) ? updates : []) {
if (!update?.id) {
continue;
}
// Skip full-metadata snapshots (see the docblock): only real deltas become GroupEvents.
if ('participants' in update || 'creation' in update || 'subjectTime' in update || 'owner' in update) {
continue;
}
const changes: NonNullable<GroupEvent['changes']> = {};
if (typeof update.subject === 'string') changes.subject = update.subject;
if (typeof update.desc === 'string') changes.description = update.desc;
if (typeof update.announce === 'boolean') changes.announce = update.announce;
if (typeof update.restrict === 'boolean') changes.locked = update.restrict;
const payload: GroupEvent = {
kind: 'update',
groupId: this.host.toNeutralJid(update.id),
participantIds: [],
changes,
timestamp: Math.floor(Date.now() / 1000),
};
const actor = update.authorPn ?? update.author;
if (actor) {
payload.actorId = this.host.toNeutralJid(actor);
}
this.host.getOnGroupEvent()?.(payload);
}
}
/**
* Baileys `call` events carry the whole call lifecycle; only the `offer` status is a NEW incoming
* call (ringing/preaccept/timeout/reject/accept/terminate are progress and hang-up updates and
* are skipped). Offline-replayed offers (missed-while-disconnected) and the account's own
* outgoing calls are skipped too. The raw `from` JID is cached keyed by call id —
* sock.rejectCall() needs it verbatim later, when the event itself is long gone.
*/
handleCallEvents(calls: WACallEvent[]): void {
for (const call of Array.isArray(calls) ? calls : []) {
if (!call || !call.id || !call.from) {
continue;
}
// An ended call takes its own path and returns. It must never fall through to the offer
// handling below: a declined call arriving there would be published as a fresh incoming call
// and, with auto-reject enabled, answered as one.
if (call.status !== 'offer') {
this.reportCallOutcome(call);
continue;
}
// Baileys replays offers for calls missed while disconnected with offline: true
// (Socket/messages-recv.js:1458 `offline: !!attrs.offline`; WACallEvent.offline is
// non-optional). Those calls are long dead — emitting call.received (and, with
// autoRejectCalls, rejecting a stale call) would be wrong, so drop them before caching.
if (call.offline) {
continue;
}
// WACallEvent has no fromMe flag, but WhatsApp can relay the account's own outgoing-call
// signaling — skip a call whose from/chatId is ourselves (the wwjs adapter's call.fromMe
// guard). Null-safe: with no socket user there is no own id to compare, so nothing is skipped.
const selfJid = this.host.normalizedSelfJid();
if (selfJid) {
const self = this.host.toNeutralJid(selfJid);
if (this.host.toNeutralJid(call.from) === self || this.host.toNeutralJid(call.chatId) === self) {
continue;
}
}
// Baileys maps both the `offer` and `offer_notice` wire tags onto status 'offer' carrying the
// same call-id, so a single call can reach this loop more than once. Cache first and emit
// only for an id not already live, otherwise one call surfaces as several `call.received`
// events.
const published = {
from: this.host.toNeutralJid(call.callerPn ?? call.from),
isVideo: call.isVideo === true,
isGroup: call.isGroup === true,
};
// Offer and offer_notice carry one call id, so another tag of the call being rejected is neither a new
// ring nor another call: it must not put the handle back or announce the call a second time. Its caller
// may be spelled as a lid on one tag and as a phone number on the next, so the published identity counts too.
const rejection = this.rejections.get(call.id);
if (
this.isPending(call.id, rejection) &&
(rejection?.entry.callFrom === call.from || rejection?.entry.from === published.from)
) {
continue;
}
if (!this.cacheLiveCall(call.id, call.from, published)) {
continue;
}
const payload: IncomingCallEvent = {
callId: call.id,
// callerPn is the phone-dialect twin of a lid caller: prefer it so the neutral caller id
// does not depend on whether the lid->pn mapping happens to be learned yet (same rule as
// the group actor ids above).
from: this.host.toNeutralJid(call.callerPn ?? call.from),
isVideo: call.isVideo === true,
isGroup: call.isGroup === true,
// The event carries a real Date; fall back to receipt time when absent/unparseable.
timestamp:
call.date instanceof Date && !Number.isNaN(call.date.getTime())
? Math.floor(call.date.getTime() / 1000)
: Math.floor(Date.now() / 1000),
};
this.host.getOnCall()?.(payload);
}
}
/**
* Publish the end of a ringing call.
*
* Only the three statuses that mean something to a consumer are mapped. WhatsApp also sends
* `ringing`, `preaccept`, `transport` and `relaylatency` — transport-level chatter with no
* user-visible meaning — and `terminate`, which covers both a caller hanging up before the call
* was answered and either side ending an answered one, with nothing in the event to tell them
* apart. Publishing `terminate` as an outcome would therefore be wrong roughly half the time.
*
* The cached live-call handle is dropped here rather than left to expire: the call is over, and a
* `rejectCall` arriving afterwards should report not-found instead of acting on a dead call.
*/
private reportCallOutcome(call: WACallEvent): void {
// `terminate` publishes no outcome (see above) but DOES end the call — drop the handle so a
// rejectCall arriving afterwards reports not-found instead of acting on a dead call. A rejection
// already pending keeps its right to report its own success (see rejectCall). The other
// unmapped statuses (ringing/preaccept/transport/relaylatency) are chatter on a call that is
// still live and must stay rejectable.
if (call.status === 'terminate') {
const rejection = this.rejections.get(call.id);
if (rejection) rejection.ended = true;
this.liveCalls.delete(call.id);
return;
}
const outcome = CALL_OUTCOMES[call.status];
if (!outcome) return;
const rejection = this.rejections.get(call.id);
const live = this.liveCalls.get(call.id) ?? (this.isPending(call.id, rejection) ? rejection?.entry : undefined);
this.rejections.delete(call.id);
this.liveCalls.delete(call.id);
// Offline replay is the same hazard as on the offer path: WhatsApp resends the signalling for
// calls that ended while this session was disconnected, and announcing those as fresh outcomes
// would report last week's declined call as if it just happened.
if (call.offline) return;
// An outcome for a call this session never saw ring is not actionable — it belongs to another
// device's conversation, or predates the connection — and would arrive with no caller identity
// beyond the raw jid. Dropping it keeps the event stream to calls the consumer already knows.
if (!live) return;
this.host.getOnCallOutcome()?.({
callId: call.id,
from: this.host.toNeutralJid(call.callerPn ?? call.from),
outcome,
isVideo: call.isVideo === true,
isGroup: call.isGroup === true,
timestamp:
call.date instanceof Date && !Number.isNaN(call.date.getTime())
? Math.floor(call.date.getTime() / 1000)
: Math.floor(Date.now() / 1000),
});
}
/**
* Map Baileys' `presence.update` onto the neutral event.
*
* The payload is a per-participant map even for a 1:1 chat, where it holds the one contact — so
* the shape is preserved rather than flattened, and a group reports everyone WhatsApp mentioned.
* Ids are neutralized on both the chat and each participant, so a consumer never sees a raw
* `@s.whatsapp.net` or a lid that the phone-dialect side of the API would not accept back.
*
* `lastSeen` is absent far more often than not: WhatsApp withholds it whenever the contact's
* privacy settings do, which is the default for most accounts. That is not an error and is not
* substituted with a guess.
*/
handlePresenceUpdate(update: { id?: string; presences?: Record<string, RawPresence> }): void {
const report = this.host.getOnPresenceUpdate();
if (!report || !update?.id || !update.presences) return;
const participants: ParticipantPresence[] = [];
for (const [participant, data] of Object.entries(update.presences)) {
const state = data?.lastKnownPresence;
// An entry with no state says nothing; forwarding it as a guessed 'unavailable' would report
// a contact offline on the strength of a malformed payload.
if (!state || !PRESENCE_STATES.has(state)) continue;
participants.push({
id: this.host.toNeutralJid(participant),
state,
...(typeof data.lastSeen === 'number' && Number.isFinite(data.lastSeen) ? { lastSeen: data.lastSeen } : {}),
});
}
if (participants.length === 0) return;
const groupOnlineCount = Object.values(update.presences).find(
p => typeof p?.groupOnlineCount === 'number',
)?.groupOnlineCount;
this.host.getOnPresenceUpdate()?.({
chatId: this.host.toNeutralJid(update.id),
participants,
...(typeof groupOnlineCount === 'number' ? { groupOnlineCount } : {}),
});
}
/**
* Cache a ringing call's raw caller JID for a later rejectCall(). Lazy expiry: inserting a new
* call drops already-expired entries, so a session that receives calls but never rejects them
* can't grow the map without bound; an entry that never sees another call is tiny and is dropped
* on teardown (disconnect/logout/destroy) or at the next call. No per-entry timer to clean up.
*
* Returns true when `callId` was not already ringing, which is what makes `call.received` fire
* once per call rather than once per upstream offer tag. A repeat offer still refreshes the
* entry, so a long-ringing call stays rejectable for a full TTL from the most recent signal.
*/
private cacheLiveCall(
callId: string,
callFrom: string,
published: { from: string; isVideo: boolean; isGroup: boolean },
): boolean {
const now = Date.now();
for (const [id, entry] of this.liveCalls) {
if (entry.expiresAt <= now) {
this.liveCalls.delete(id);
}
}
const isNewCall = !this.liveCalls.has(callId);
this.rejections.delete(callId);
// The published identity is cached alongside the raw JID so a rejection issued through the API
// can report the same shape the engine-observed outcomes do — the call event itself is long
// gone by then.
this.liveCalls.set(callId, { callFrom, expiresAt: now + BaileysEvents.LIVE_CALL_TTL_MS, ...published });
return isNewCall;
}
/** Whether `rejection` is still the pending one for the call: nothing has ended the call since it began. */
private isPending(callId: string, rejection: CallRejection | undefined): boolean {
return (
rejection !== undefined && this.rejections.get(callId) === rejection && this.liveCalls.clears === rejection.clears
);
}
/**
* Reject a currently-ringing call. The entry is evicted before the attempt, so a rejected call does not
* become rejectable again. A signal that publishes its own outcome meanwhile makes this attempt stale; a
* stale attempt publishes nothing. Otherwise a success publishes `rejected`, a `terminate` that arrived
* first included. A failed attempt leaves the call ringing, so its entry is put back for a retry, unless
* something ended the call meanwhile (any signal, a `terminate`, another call under the id, a teardown).
* An unknown id or an expired entry maps to CallNotFoundError (HTTP 404).
* A failure of the library's rejectCall() itself propagates as-is.
*/
async rejectCall(callId: string): Promise<void> {
const entry = this.liveCalls.get(callId);
if (!entry || entry.expiresAt <= Date.now()) {
this.liveCalls.delete(callId);
throw new CallNotFoundError(callId);
}
const sock = this.host.getSocketOrNull();
if (!sock) {
throw new EngineNotReadyError('Cannot reject a call before the engine is initialized.');
}
this.liveCalls.delete(callId);
const rejection: CallRejection = { entry, clears: this.liveCalls.clears, ended: false };
this.rejections.set(callId, rejection);
let current: boolean;
try {
await withQueryDeadline(
sock.rejectCall(callId, entry.callFrom),
BAILEYS_QUERY_BUDGET_MS,
'WhatsApp did not confirm the call rejection in time',
);
current = this.isPending(callId, rejection);
} catch (err) {
if (
!rejection.ended &&
this.isPending(callId, rejection) &&
!this.liveCalls.has(callId) &&
entry.expiresAt > Date.now()
) {
this.liveCalls.set(callId, entry);
}
throw err;
} finally {
if (this.rejections.get(callId) === rejection) this.rejections.delete(callId);
}
if (!current) return;
// A rejection made HERE produces no inbound `reject` signal to observe, so without this the
// one outcome the caller definitely knows about — the one they asked for — was the only one
// never published. Emitted only after the socket accepted it, and the entry is already evicted,
// so a server echo arriving later cannot publish a second time.
this.host.getOnCallOutcome()?.({
callId,
from: entry.from,
outcome: 'rejected',
isVideo: entry.isVideo,
isGroup: entry.isGroup,
timestamp: Math.floor(Date.now() / 1000),
});
}
/**
* Coerce one `group-participants.update` entry to a neutral user id. Since Baileys v7 the entries
* are parsed JSON objects (`{ id, phoneNumber?, lid?, ... }`, see Socket/messages-recv.js), not
* plain JID strings: prefer the phone JID when present (a lid `id` with a known phone resolves to
* the same neutral @c.us via the mapping, but the inline phoneNumber needs no lookup), then the
* bare id, then the lid. Plain-string entries (the pre-v7 shape) pass through the same normalizer.
*/
private toNeutralGroupParticipantId(entry: unknown): string | null {
if (typeof entry === 'string') {
return entry ? this.host.toNeutralJid(entry) : null;
}
if (entry && typeof entry === 'object') {
const e = entry as { phoneNumber?: unknown; id?: unknown; lid?: unknown };
const jid = [e.phoneNumber, e.id, e.lid].find((v): v is string => typeof v === 'string' && v.length > 0);
return jid ? this.host.toNeutralJid(jid) : null;
}
return null;
}
/**
* Download inbound media via a stream, accumulating chunks but ABORTING (destroy + discard) once the
* running total exceeds `maxBytes`. On that abort it resolves `{ overflowBytes }`, the bytes received
* when the cap tripped; past the wall-clock deadline it resolves null. Uses
* `downloadMediaMessage(..., 'stream')` (not the raw `downloadContentFromMessage`) so the library's
* expired-media re-upload retry is kept; for under-cap media the concatenated buffer is byte-identical
* to the 'buffer' mode it replaces.
*/
private async downloadInboundMediaCapped(
msg: WAMessage,
maxBytes: number,
): Promise<Buffer | { overflowBytes: number } | null> {
// Hold the stream handle in the outer scope so the timeout can destroy it. A genuine
// download/read error still rejects (propagating to the caller's catch as before).
let stream: (AsyncIterable<Buffer> & { destroy?: () => void }) | undefined;
// The timeout can fire before the stream exists (an expired-media re-upload wait, a slow response):
// the abandoned download must then stop on its own instead of buffering outside the limiter.
let timedOut = false;
// Settles the gate task at the deadline. Without it the process-wide slot is held until the body
// settles, and a fetch stuck before the stream exists (an expired-media re-upload the phone never
// answers waits with no timeout until the socket closes) would keep that slot for hours, starving
// every other session's media. Freeing it early is safe: nothing is buffered before the stream
// exists, and a stream that turns up late is destroyed by the `timedOut` check below.
let releaseSlot: () => void = () => undefined;
const deadlinePassed = new Promise<Buffer>(resolve => {
releaseSlot = () => resolve(Buffer.alloc(0));
});
const body = async (): Promise<Buffer | { overflowBytes: number }> => {
if (timedOut) {
return Buffer.alloc(0);
}
const b = await this.host.loadLib();
// The address comes from the sender, and so does a re-upload answer (encrypted with the
// sender's own media key): both are checked before Baileys fetches them.
const assertWhatsAppSource = (m: WAMessage): WAMessage => {
if (!isWhatsAppMediaSource(b, m.message)) {
throw new Error('Inbound media address is not a WhatsApp media host; not fetched');
}
return m;
};
assertWhatsAppSource(msg);
const sock = this.host.getSocket();
// A proxied session must not fetch media around its proxy (#859). Baileys reads the dispatcher
// from the nested `options`; a top-level one is ignored. Read after the socket: once the session
// is torn down getSocket() throws, and a dispatcher built then would never be closed.
const dispatcher = this.host.getFetchDispatcher();
stream = (await b.downloadMediaMessage(
msg,
'stream',
dispatcher ? { options: { dispatcher } as RequestInit } : {},
{
logger: createSilentLogger(),
reuploadRequest: async m => assertWhatsAppSource(await sock.updateMediaMessage(m)),
},
)) as AsyncIterable<Buffer> & { destroy?: () => void };
if (timedOut) {
stream.destroy?.();
return Buffer.alloc(0);
}
const chunks: Buffer[] = [];
let total = 0;
for await (const chunk of stream) {
if (timedOut) {
break;
}
total += chunk.length;
if (total > maxBytes) {
stream.destroy?.();
return { overflowBytes: total };
}
chunks.push(chunk);
}
return Buffer.concat(chunks);
};
// The wait for the process-wide gate sits inside the deadline below, so a contended gate cannot
// hold this session's inbound handler longer than MEDIA_DOWNLOAD_TIMEOUT_MS.
const download = runUnderGlobalMediaGate(() => {
const run = body();
// The abandoned body can still reject later (the socket closing under a re-upload wait).
run.catch(() => undefined);
return Promise.race([run, deadlinePassed]);
});
// A slow/trickling sender never trips the byte cap, so without a deadline it pins a concurrency
// slot (and, on Baileys, the whole inbound handler) indefinitely. On timeout, destroy the stream
// and treat it as no usable media.
return withInboundDownloadTimeout(download, inboundMediaTimeoutMs(), () => {
timedOut = true;
stream?.destroy?.();
releaseSlot();
});
}
/**
* Resolve the media payload of an inbound message: the omitted marker when the download is skipped
* or disabled, the same marker when the declared size trips the pre-download gate, otherwise the
* capped stream-download. Impure by nature — it downloads, logs and reads env — so it stays beside
* {@link downloadInboundMediaCapped} rather than moving to the pure mapper module.
*
* `skipMediaDownload` is a plain boolean so the `||` keeps its short-circuit order:
* `isMediaDownloadEnabled()` reads `process.env` at call time and must not run when skip is set.
*/
private async resolveInboundMedia(
msg: WAMessage,
contentType: string | undefined,
content: NonNullable<WAMessage['message']>,
b: typeof BaileysLib,
skipMediaDownload: boolean,
room?: { ticket?: InboundTicket; yieldSlot?: <R>(fn: () => Promise<R>) => Promise<R> },
): Promise<IncomingMessage['media']> {
if (!isBaileysMediaType(contentType)) {
return undefined;
}
// The outbound "sent" echo passes skipMediaDownload: the API caller already holds the media and
// the REST send path persists it, so re-downloading it here would buy nothing. This is where
// Baileys deliberately diverges from wwjs, whose echo does download the payload
// (wwebjs-message-events.ts) because a phone-composed send has no other source for it.
if (skipMediaDownload || !isMediaDownloadEnabled()) {
// Emit the omitted marker so the media field is present (webhook/n8n/dashboard contract).
// mimetype is available pre-download from the message content.
const normalizedContent = b.normalizeMessageContent(content) ?? content;
const subMessage = mediaSubMessage(normalizedContent);
return {
mimetype: subMessage?.mimetype ?? '',
filename: normalizedContent.documentMessage?.fileName ?? undefined,
omitted: true,
sizeBytes: coerceDeclaredSize(subMessage?.fileLength),
};
}
// normalizeMessageContent unwraps documentWithCaptionMessage / viewOnceMessage / ephemeralMessage
// so we reach the inner media sub-message — needed BEFORE download for the declared-size pre-gate.
const normalizedContent = b.normalizeMessageContent(content) ?? content;
const subMessage = mediaSubMessage(normalizedContent);
const mimetype = subMessage?.mimetype ?? '';
const filename = normalizedContent.documentMessage?.fileName ?? undefined;
const maxBytes = inboundMediaMaxBytes();
const declared = coerceDeclaredSize(subMessage?.fileLength);
if (declared > maxBytes) {
// Pre-download gate: an honest over-cap sender's media is never decrypted into heap at all.
// Baileys does not check the decrypted bytes against the declared size, so a sender can
// understate it; the streaming abort below is the bound for that case.
this.host.logger.warn('Inbound media declared size exceeds MEDIA_DOWNLOAD_MAX_BYTES; skipped download', {
msgId: msg.key.id,
sizeBytes: declared,
});
return { mimetype, filename, omitted: true, sizeBytes: declared };
}
try {
// Where payloads wait for their rows (PostgreSQL), download only into a slot of the session's
// room, held until the row is written. The inbound limiter slot is given up while waiting, so
// other chats' messages keep flowing. No room in time: the marker, and nothing downloaded.
const ticket = room?.ticket;
if (ticket) {
const granted = ticket.reserve();
const yieldSlot = room?.yieldSlot ?? (<R>(fn: () => Promise<R>) => fn());
if (!(granted === true || (granted !== false && (await yieldSlot(() => granted))))) {
this.host.logger.warn('No room for inbound media within the wait; emitting the omitted marker', {
msgId: msg.key.id,
sizeBytes: declared,
});
return { mimetype, filename, omitted: true, sizeBytes: declared };
}
}
// Stream-download with a running-total abort so a sender who understates fileLength still
// can't materialise an over-cap blob. For under-cap media this yields the identical buffer.
const buf = await this.downloadInboundMediaCapped(msg, maxBytes);
if (buf === null) {
// Nothing proves the real size, so report the declared one, as the failure branch below does.
this.host.logger.warn('Inbound media download passed MEDIA_DOWNLOAD_TIMEOUT_MS; emitting omitted marker', {
msgId: msg.key.id,
sizeBytes: declared,
});
return { mimetype, filename, omitted: true, sizeBytes: declared };
}
if (!Buffer.isBuffer(buf)) {
// The bytes received are a lower bound above the cap; the declared size passed the pre-gate, so
// it is smaller and says nothing here.
const sizeBytes = buf.overflowBytes;
this.host.logger.warn('Inbound media download exceeded MEDIA_DOWNLOAD_MAX_BYTES; emitting omitted marker', {
msgId: msg.key.id,
sizeBytes,
});
return { mimetype, filename, omitted: true, sizeBytes };
}
// capInboundMedia is the last line (lazy base64, never persist/webhook/broadcast an over-cap
// blob); the real heap bound is the pre-gate + streaming abort + concurrency limiter.
return capInboundMedia({
mimetype,
filename,
sizeBytes: buf.byteLength,
toBase64: () => buf.toString('base64'),
});
} catch (err) {
// A download failure yields the omitted marker, never a propagated throw: the media field stays
// present, matching the skip/pre-gate/abort exits above. The declared size is the honest number
// here: the download never completed, so no measured size exists.
this.host.logger.warn('Inbound media download failed; emitting the omitted marker', {
error: err instanceof Error ? err.message : String(err),
msgId: msg.key.id,
});
return { mimetype, filename, omitted: true, sizeBytes: declared };
}
}
async mapMessage(
msg: WAMessage,
contentType: string | undefined,
opts?: {
skipMediaDownload?: boolean;
ticket?: InboundTicket;
yieldSlot?: <R>(fn: () => Promise<R>) => Promise<R>;
},
): Promise<IncomingMessage> {
const b = await this.host.loadLib();
const content = msg.message ?? {};
// Read body/location/media/context off the NORMALIZED content: a disappearing message
// (ephemeralMessage), a captioned document (documentWithCaptionMessage) and viewOnce/edited wrappers
// nest the real payload under an inner message, so the raw wrapper exposes none at top level.
// Identity no-op when unwrapped.
const normalized = b.normalizeMessageContent(content) ?? content;
// Body: text first, then media caption, then WhatsApp Business interactive shapes (#562).
const body = extractBaileysBody(normalized);
const location = extractBaileysLocation(normalized, contentType);
const media = await this.resolveInboundMedia(msg, contentType, content, b, opts?.skipMediaDownload === true, opts);
// The quote, the disappearing-messages timer, the mentions and the status styling all come from
// one region of the content — see BaileysMessageContext.
const context = extractBaileysContext(normalized);
// Commerce ids (order token, product id): the generic path sees an empty body and drops them,
// and they are the only handle a caller has on the order or the product.
const commerce = extractBaileysCommerce(normalized, contentType);
// Button / list / native-flow reply ids: body carries the visible label; this is the stable id.
const button = extractBaileysButtonReply(normalized, contentType);
// Prompt choices (Sim/Não, list rows, …) offered by a business interactive message.
const buttons = extractBaileysButtons(normalized, contentType);
return buildIncomingMessageFromBaileys(
{
id: msg.key.id ?? '',
remoteJid: msg.key.remoteJid!,
fromMe: msg.key.fromMe === true,
participant: keyParticipant(msg.key),
body,
contentType,
isPtt: normalized.audioMessage?.ptt === true,
timestamp: toUnixSeconds(msg.messageTimestamp),
pushName: msg.pushName ?? undefined,
selfJid: this.host.normalizedSelfJid(),
media,
location,
quotedMessage: context.quotedMessage,
order: commerce.order,
product: commerce.product,
poll: extractBaileysPoll(normalized),
button,
buttons,
isCatalogShare: isBaileysCatalogShare(normalized),
ephemeralDuration: context.ephemeralDuration,
mentionedJids: context.mentionedJids,
backgroundArgb: context.backgroundArgb,
font: context.font,
},
jid => this.host.toNeutralJid(jid),
);
}
/** Protocol-message edit timestamps are milliseconds; the enclosing message timestamp is seconds. */
private toEditUnixSeconds(
timestampMs: number | { toNumber(): number } | null | undefined,
fallback: number | { toNumber(): number } | null | undefined,
): number {
if (timestampMs == null) return toUnixSeconds(fallback);
const milliseconds = typeof timestampMs === 'number' ? timestampMs : timestampMs.toNumber();
return Number.isFinite(milliseconds) ? Math.floor(milliseconds / 1000) : toUnixSeconds(fallback);
}
}