Free, Open Source, Self-Hosted WhatsApp API Gateway
TypeScript apibotgatewayself-hostedwhatsappwhatsapp-apiwhatsapp-automationwhatsapp-botwhatsapp-gatewaywhatsapp-gateway-apiwhatsapp-webwhatsapp-web-api
import { BadRequestException } from '@nestjs/common';
import * as wwebjs from 'whatsapp-web.js';
import { MessageTypes, type Chat, type Client } from 'whatsapp-web.js';
import { ChatSummary, ChatState } from '../interfaces/whatsapp-engine.interface';
import { EngineTransportError } from '../../common/errors/engine-transport.error';
import { chatKind, isChannelJid } from '../identity/wa-id';
import { WwebjsMessaging } from './wwebjs-messaging';
import { type WwebjsEngineHost, rethrowIfNavigation } from './wwebjs-host';
import { isProtocolTimeout } from './wwebjs-lifecycle';
import { mapWwebjsMessageType } from './message-mapper';
/**
* Build the chat list IN-PAGE with the same `window.WWebJS.getChatModel` whatsapp-web.js's own
* `client.getChats()` maps, yielding to the page event loop every 256 chats so the liveness probe's
* queued `getState()` evaluate can interleave. The library starts every getChatModel in one `map`,
* and a personal chat reaches no await at all (serialize() plus its last message), so on a large chat
* list that map is one uninterrupted synchronous stretch that starves the probe and lets the watchdog
* tear a healthy session down mid-read: the #1501 shape readLeanContacts fixed for contacts.
*
* The models and their order are unchanged, the group metadata updates still overlap, and one chat
* whose model rejects still rejects the whole read, as upstream does.
*/
export async function readChatModels(): Promise<unknown[]> {
const w = window as unknown as {
require: (m: string) => { Chat: { getModelsArray: () => unknown[] } };
WWebJS: { getChatModel: (chat: unknown) => Promise<unknown> };
};
// A copy: getModelsArray() is the collection's live array, which re-sorts on a new message and
// grows on a new chat, so indexing it across the yields below would read one chat twice and skip
// another. Upstream's single synchronous map never let it change underneath.
const chats = w.require('WAWebCollections').Chat.getModelsArray().slice();
const pending: Promise<unknown>[] = [];
for (let i = 0; i < chats.length; i++) {
const model = w.WWebJS.getChatModel(chats[i]);
// Handled here so a rejection that lands during a yield is not reported as unhandled; the
// Promise.all below still rejects with it.
model.catch(() => undefined);
pending.push(model);
if ((i & 0xff) === 0xff) await new Promise(resolve => setTimeout(resolve));
}
return Promise.all(pending);
}
/** The chat structures are classes at runtime; index.d.ts declares them as interfaces only. */
type ChatConstructor = new (client: Client, data: unknown) => Chat;
const { GroupChat, PrivateChat } = wwebjs as unknown as { GroupChat: ChatConstructor; PrivateChat: ChatConstructor };
/**
* Turn a failure that says the page is gone into the retryable 503 every chat operation answers: a dead
* page (reported as the early death signal) or a read that outran the protocol budget. Anything else
* returns, for the caller to handle. A chat action that reported a dead page as "WhatsApp declined" (an
* opaque `false`) let the caller retry against a corpse.
*/
function rethrowTransportFailure(
host: WwebjsEngineHost,
error: unknown,
context: string,
activity: string,
timedOutMessage = `WhatsApp Web did not answer in time while ${activity}`,
): void {
rethrowIfNavigation(host, error);
if (host.isPageTransportError(error)) {
host.reportIfPageTransportError(error, context);
throw new EngineTransportError(`Transport died while ${activity}`);
}
if (isProtocolTimeout(error)) {
throw new EngineTransportError(timedOutMessage);
}
}
/**
* The whole chat list through {@link readChatModels}, rehydrated the way whatsapp-web.js's
* ChatFactory does for these entries, so every mapped field reads exactly as `client.getChats()`
* gave it. Shared by the chat and group lists. A dead page answers 503 with the death signal, a read
* that outran the protocol budget answers 503 without one, and anything else is rethrown.
*/
export async function listChats(host: WwebjsEngineHost, context: string): Promise<Chat[]> {
const client = host.getClient();
const page = (client as unknown as { pupPage: { evaluate: <T>(fn: () => Promise<T>) => Promise<T> } }).pupPage;
let models: unknown[];
try {
models = await page.evaluate(readChatModels);
} catch (error) {
// Same split every sibling read makes (see getChatsByLabel): a dead page is a 503 and an
// early death signal, not an opaque 500 under a status that still says READY (#1081).
rethrowTransportFailure(
host,
error,
context,
'listing chats',
'WhatsApp Web did not answer the chat list read in time',
);
throw error;
}
return models.map(data =>
(data as { isGroup?: boolean }).isGroup ? new GroupChat(client, data) : new PrivateChat(client, data),
);
}
/**
* Chat-list operations extracted from WhatsAppWebJsAdapter. The adapter keeps the public methods as
* thin forwarders and injects the shared host surface (./wwebjs-host) via closures, so the delegate
* never touches lifecycle state directly. Presence (sendChatState) resolves the recipient through
* the messaging delegate's send-id cache, exactly like a send.
*/
export class WwebjsChats {
constructor(
private readonly host: WwebjsEngineHost,
private readonly messaging: WwebjsMessaging,
) {}
/** Post-ensureReady client handle. */
private client(): Client {
return this.host.getClient();
}
async getChats(): Promise<ChatSummary[]> {
this.host.ensureReady();
const chats = await listChats(this.host, 'getChats');
const summaries: ChatSummary[] = [];
let skipped = 0;
// Map the raw whatsapp-web.js chat objects to the library-agnostic ChatSummary
// shape so that no library types leak past the engine boundary. Some WA system
// or channel-like entries can lack the normal serialized id; skip those instead
// of failing the whole dashboard chats request.
for (const chat of chats) {
const id = chat.id?._serialized;
if (!id) {
skipped++;
continue;
}
summaries.push({
id,
name: chat.name || id,
isGroup: Boolean(chat.isGroup),
kind: chatKind(id),
unreadCount: chat.unreadCount || 0,
timestamp: chat.timestamp || 0,
// A location message's body is the base64 map thumbnail; don't surface it as the chat preview.
lastMessage: chat.lastMessage?.type === MessageTypes.LOCATION ? '📍' : chat.lastMessage?.body || undefined,
lastMessageType: chat.lastMessage ? mapWwebjsMessageType(chat.lastMessage.type) : undefined,
archived: Boolean(chat.archived),
pinned: Boolean(chat.pinned),
// Chat.isMuted is the current verdict; muteExpiration is wwjs epoch SECONDS with -1 = forever.
muted: Boolean(chat.isMuted),
// Expose the expiry as ms (0 = indefinite), present only when muted, per ChatSummary.
muteExpiration: chat.isMuted
? (chat.muteExpiration ?? 0) > 0
? (chat.muteExpiration ?? 0) * 1000
: 0
: undefined,
});
}
if (skipped > 0) {
this.host.logger.warn(`Skipped ${skipped} chat(s) without a serialized id`);
}
return summaries;
}
async sendSeen(chatId: string): Promise<boolean> {
this.host.ensureReady();
try {
const chat = await this.client().getChatById(chatId);
return await chat.sendSeen();
} catch (error) {
// A dead page is a 503 and an early death signal, not an opaque `false` (see rethrowTransportFailure).
rethrowTransportFailure(this.host, error, 'sendSeen', 'marking a chat as read');
this.host.logger.error(`Error marking chat ${chatId} as read`, String(error));
return false;
}
}
async clearChatMessages(chatId: string): Promise<boolean> {
this.host.ensureReady();
try {
// An unknown chat needs no special case: getChatById resolves undefined for one, and the
// resulting TypeError lands in the catch below as the same `false` the injected helper
// returns for a chat it cannot find. Same shape as sendSeen/archiveChat above.
const chat = await this.client().getChatById(chatId);
return await chat.clearMessages();
} catch (error) {
// A dead page is a 503 and an early death signal, not an opaque `false` (see rethrowTransportFailure).
rethrowTransportFailure(this.host, error, 'clearChatMessages', 'clearing a chat');
this.host.logger.error(`Error clearing messages in chat ${chatId}`, String(error));
return false;
}
}
async archiveChat(chatId: string, archive: boolean): Promise<boolean> {
this.host.ensureReady();
try {
// Client.archiveChat/unarchiveChat, NOT Chat.archive() — the Chat method resolves void.
//
// Their return value is deliberately DISCARDED. Despite looking like a success flag they
// resolve the chat's NEW ARCHIVE STATE, hard-coded: archiveChat always returns true and
// unarchiveChat always returns false (Client.js:2009-2031, "Changes and returns the archive
// state of the Chat"). Surfacing that as `success` reports every successful UNARCHIVE as
// success:false — which this API's contract defines as "the engine declined to act".
//
// whatsapp-web.js offers no refusal signal here at all, so the honest answer is "it did not
// throw": an unknown chat makes the page-side Cmd.archiveChat reject, which lands below.
if (archive) {
await this.client().archiveChat(chatId);
} else {
await this.client().unarchiveChat(chatId);
}
return true;
} catch (error) {
// A dead page is a 503 and an early death signal, not an opaque `false` (see rethrowTransportFailure).
rethrowTransportFailure(this.host, error, 'archiveChat', 'archiving a chat');
this.host.logger.error(`Error ${archive ? 'archiving' : 'unarchiving'} chat ${chatId}`, String(error));
return false;
}
}
/**
* whatsapp-web.js signals a chat it cannot resolve by rejecting deep inside the page — `No LID for
* user` from pin's WID lookup, a TypeError from the evaluate inside `Client._muteUnmuteChat` for
* mute. Both surfaced as a bare 500, a status neither route declares, while every older member of
* this family answers an unknown chat gracefully.
*
* Resolving the chat first turns that into the 400 the contract already promises. It deliberately
* does NOT wrap the pin/mute call itself: a page-side rejection for a chat that DOES exist is the
* one signal a renamed page internal produces, and demoting it to "bad input" would hide a total
* capability failure — the shape `createGroup` turned out to have. `getChatById` is the same
* resolution five neighbours here already trust, and it reports an unknown chat either way it can,
* by resolving undefined or by rejecting.
*/
private async requireResolvableChat(chatId: string): Promise<void> {
let chat: unknown;
try {
chat = await this.client().getChatById(chatId);
} catch (error) {
// A dead page resolves NOTHING, so swallowing every rejection here reported it as "no such
// chat" and named the caller's chatId as the problem. The other chat operations split that case
// out; without this, the same file answered a dead page two different ways.
rethrowTransportFailure(this.host, error, 'requireResolvableChat', 'resolving a chat');
chat = undefined; // an unknown chat rejects too — that is the 400 below
}
if (!chat) throw new BadRequestException(`Chat ${chatId} does not exist on this session`);
}
/**
* The write leg of mute, pin and the account's own presence. A dead page or an expired protocol
* timeout is a 503 (mute, unmute, pin, unpin and a presence change all converge when repeated) and
* a dead page is reported as the early death signal. Any other rejection is rethrown untouched,
* for the reason above.
*/
private async chatWrite<T>(context: string, op: () => Promise<T>): Promise<T> {
try {
return await op();
} catch (error) {
rethrowIfNavigation(this.host, error);
if (this.host.isPageTransportError(error)) {
this.host.reportIfPageTransportError(error, context);
throw new EngineTransportError(`Transport died during ${context}`);
}
if (isProtocolTimeout(error)) {
throw new EngineTransportError(`WhatsApp Web did not answer in time during ${context}`);
}
throw error;
}
}
async muteChat(chatId: string, muteUntil: number | null): Promise<void> {
this.host.ensureReady();
await this.requireResolvableChat(chatId);
if (muteUntil === null) {
await this.chatWrite('muteChat', () => this.client().unmuteChat(chatId));
return;
}
// muteUntil is epoch milliseconds, which is what Date wants; Client.muteChat floors it to the
// seconds its page-side call expects. The Baileys side takes the same milliseconds unmodified.
await this.chatWrite('muteChat', () => this.client().muteChat(chatId, new Date(muteUntil)));
}
async pinChat(chatId: string, pin: boolean): Promise<boolean> {
this.host.ensureReady();
// Not `return false` for an unknown chat: `false` is already taken here, and means the three-pin
// cap refused a real chat. Conflating the two would tell a caller with a stale chatId that its
// pin quota is full.
await this.requireResolvableChat(chatId);
if (!pin) {
// unpinChat resolves the chat's NEW pin state, which is `false` for every successful unpin —
// both on its early-out for an already-unpinned chat and after actually unpinning
// (Client.js:2073-2084). Forwarding it would report every success as a refusal, the same trap
// archiveChat documents. Discard it: an unpin that did not throw succeeded.
await this.chatWrite('pinChat', () => this.client().unpinChat(chatId));
return true;
}
// In this direction the return value IS information. WhatsApp caps pinned chats at three
// (MAX_PIN_COUNT, Client.js:2054-2063) and the page returns false without pinning once that is
// met, so a false here is a real refusal the caller needs to see.
return await this.chatWrite('pinChat', () => this.client().pinChat(chatId));
}
async markUnread(chatId: string): Promise<boolean> {
this.host.ensureReady();
if (isChannelJid(chatId)) {
// A channel resolves to a wwebjs `Channel`, which has no markUnread() — there is no unread
// state to toggle on a channel. Report the no-op rather than throwing a TypeError.
return false;
}
try {
const chat = await this.client().getChatById(chatId);
// Chat.markUnread() resolves void, so synthesize the boolean from a clean call.
await chat.markUnread();
return true;
} catch (error) {
// A dead page is a 503 and an early death signal, not an opaque `false` (see rethrowTransportFailure).
rethrowTransportFailure(this.host, error, 'markUnread', 'marking a chat as unread');
this.host.logger.error(`Error marking chat ${chatId} as unread`, String(error));
return false;
}
}
async deleteChat(chatId: string): Promise<boolean> {
this.host.ensureReady();
if (isChannelJid(chatId)) {
// A channel resolves to a wwebjs `Channel`, which has no delete() (only the destructive
// deleteChannel()); a generic chat-delete must not silently unsubscribe a channel.
return false;
}
try {
const chat = await this.client().getChatById(chatId);
return await chat.delete();
} catch (error) {
// A dead page is a 503 and an early death signal, not an opaque `false` (see rethrowTransportFailure).
rethrowTransportFailure(this.host, error, 'deleteChat', 'deleting a chat');
this.host.logger.error(`Error deleting chat ${chatId}`, String(error));
return false;
}
}
/**
* Publish the account's own GLOBAL presence. Not best-effort, unlike sendChatState: the caller
* asked for a specific visibility, and swallowing a failure would leave the account silently
* online after the API reported otherwise (#871 — an always-online bot suppresses the phone's
* own notifications).
*/
async setOnlinePresence(available: boolean): Promise<void> {
this.host.ensureReady();
await this.chatWrite('setOnlinePresence', () =>
available ? this.client().sendPresenceAvailable() : this.client().sendPresenceUnavailable(),
);
}
async sendChatState(chatId: string, state: ChatState): Promise<void> {
this.host.ensureReady();
if (isChannelJid(chatId)) {
// A channel resolves to a wwebjs `Channel`, which has no presence methods
// (sendStateTyping/sendStateRecording/clearState). Presence is best-effort, so no-op.
return;
}
try {
const to = await this.messaging.resolveSendId(chatId);
const chat = await this.client().getChatById(to);
if (state === 'typing') {
await chat.sendStateTyping();
} else if (state === 'recording') {
await chat.sendStateRecording();
} else {
await chat.clearState();
}
} catch (error) {
// Presence is best-effort and already swallowed here — it never breaks the surrounding send —
// so log at WARN, not ERROR: a migrated contact routinely yields `No LID for user` on the
// presence path and an ERROR line reads as a fault when nothing actually failed (#582).
this.host.logger.warn(`Could not set chat state '${state}' for ${chatId} (best-effort)`, {
error: String(error),
});
}
}
}