Free, Open Source, Self-Hosted WhatsApp API Gateway
TypeScript apibotgatewayself-hostedwhatsappwhatsapp-apiwhatsapp-automationwhatsapp-botwhatsapp-gatewaywhatsapp-gateway-apiwhatsapp-webwhatsapp-web-api
import { type Client } from 'whatsapp-web.js';
import { InternalServerErrorException } from '@nestjs/common';
import { Contact } from '../interfaces/whatsapp-engine.interface';
import { EngineNotReadyError } from '../../common/errors/engine-not-ready.error';
import { EngineTransportError } from '../../common/errors/engine-transport.error';
import { parseWaId, userPart } from '../identity/wa-id';
import { readWid, type SerializedWid } from '../types/whatsapp-web-js.types';
import { type WwebjsEngineHost, rethrowIfNavigation, withPage } from './wwebjs-host';
import { isProtocolTimeout } from './wwebjs-lifecycle';
/** The raw whatsapp-web.js contact element type, kept local so the wwebjs `Contact` type never leaks. */
type RawWwebjsContact = Awaited<ReturnType<Client['getContacts']>>[number];
/** The six fields {@link WwebjsContacts.toContact} reads, projected in-page by {@link readLeanContacts}. */
interface LeanContact {
id: SerializedWid | string;
name?: string;
pushname?: string;
number: string;
isMyContact: boolean;
isBlocked: boolean;
}
/** What {@link readLeanContacts} returns: the readable rows, and how many models threw instead. */
interface LeanContactRead {
rows: LeanContact[];
failed: number;
firstError?: string;
}
/**
* Read the contact list IN-PAGE, projected to only the fields {@link WwebjsContacts.toContact} keeps,
* yielding to the page event loop every 256 contacts so the liveness probe's queued `getState()`
* evaluate can interleave (#1501). whatsapp-web.js's own `client.getContacts()` maps the same
* `window.WWebJS.getContactModel`, but over a `Promise.all` with no await for personal contacts, so it
* runs as one uninterrupted synchronous stretch that starves the probe on a large address book and
* makes the watchdog tear a healthy session down mid-read. The per-contact `serialize()` cost is
* unchanged; the yield is what makes the read probe-safe regardless of size.
*
* Reusing `getContactModel` keeps `id`/`number`/`name`/`pushname`/`isMyContact`/`isBlocked` byte
* identical to `getContacts()` (`Contact.number` is `data.userid`), and the raw `id` stays readable by
* {@link readWid} (`_serialized`, the post-rename `$1`, or a lid `phoneNumber` string all resolve).
* `BusinessProfile.find` is skipped: its only output, `res.businessProfile`, is not one of the six
* fields, so dropping it costs nothing and saves a network fetch per business contact.
*/
export async function readLeanContacts(): Promise<LeanContactRead> {
const w = window as unknown as {
require: (m: string) => { Contact: { getModelsArray: () => unknown[] } };
WWebJS: {
getContactModel: (contact: unknown) => {
id: SerializedWid | string;
name?: string;
pushname?: string;
userid: string;
isMyContact: boolean;
isBlocked: boolean;
};
};
};
// A copy: getModelsArray() is the collection's live array, which grows when a new contact writes,
// so indexing it across the yields below would read one contact twice and skip another.
const models = w.require('WAWebCollections').Contact.getModelsArray().slice();
const rows: LeanContact[] = [];
let failed = 0;
let firstError: string | undefined;
for (let i = 0; i < models.length; i++) {
// One model WhatsApp Web cannot read (getContactModel's getAlternateUserWid throws "Invalid get
// call using deviceWid" for a device-scoped wid, #1720) must not reject the whole walk. It is
// counted and skipped; whatsapp-web.js's own getContacts() never returned such an entry either,
// because its Promise.all rejected on it.
try {
const m = w.WWebJS.getContactModel(models[i]);
rows.push({
id: m.id,
name: m.name,
pushname: m.pushname,
number: m.userid,
isMyContact: m.isMyContact,
isBlocked: m.isBlocked,
});
} catch (error) {
failed++;
if (firstError === undefined) firstError = error instanceof Error ? error.message : String(error);
}
// Yield every 256 contacts so the getState() liveness probe can interleave (#1501);
// raise the stride if the read ever gets too chatty on a very large address book.
if ((i & 0xff) === 0xff) await new Promise(resolve => setTimeout(resolve));
}
return { rows, failed, firstError };
}
/**
* Read IN-PAGE the LID WhatsApp Web already holds for a phone id, or null when it holds none. Local only:
* unlike `client.getContactLidAndPhone`, which runs an existence query for a phone whose LID the page does
* not know, this sends nothing to WhatsApp. Self-contained, since Puppeteer ships it to the page as source.
*/
export function readCurrentLid(phoneId: string): string | null {
type Wid = { _serialized?: string; $1?: string };
const w = window as unknown as {
require: (m: string) => { createWid: (id: string) => Wid; getCurrentLid: (wid: Wid) => Wid | null | undefined };
};
const lid = w.require('WAWebApiContact').getCurrentLid(w.require('WAWebWidFactory').createWid(phoneId));
return lid?._serialized || lid?.$1 || null;
}
/**
* Contact 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.
*/
export class WwebjsContacts {
constructor(private readonly host: WwebjsEngineHost) {}
/** Post-ensureReady client handle. */
private client(): Client {
return this.host.getClient();
}
/**
* Map a raw whatsapp-web.js contact to the library-agnostic {@link Contact}. The id is read
* through {@link readWid} so both the `_serialized` and post-rename `$1` shapes resolve; a
* contact with no readable id returns null so callers can skip it instead of dereferencing
* unguarded (the shape that lets a single bad entry reject the whole request).
*/
private toContact(c: RawWwebjsContact): Contact | null {
const id = readWid(c.id);
if (!id) return null;
return {
id,
name: c.name || undefined,
pushName: c.pushname || undefined,
// whatsapp-web.js answers a contact migrated to privacy-id addressing under its phone id (the
// model's `phoneNumber`) but leaves `number` at the LID's digits, so a user id's number is read
// from the id. A LID with no known phone keeps the engine's number.
number: parseWaId(id).kind === 'user' ? userPart(id) : c.number,
isMyContact: c.isMyContact,
isBlocked: c.isBlocked,
};
}
/**
* WhatsApp Web holds a contact migrated to privacy-id addressing twice, as its LID record and its
* phone record, and {@link toContact} reads the first under the phone id, so one id comes back twice.
* The copies are folded into the first one's place, which keeps the paging order stable, and a name or
* a flag only the other copy holds survives (a block is never dropped).
*/
private static mergeById(contacts: Contact[]): Contact[] {
const byId = new Map<string, Contact>();
for (const c of contacts) {
const first = byId.get(c.id);
byId.set(
c.id,
first
? {
...first,
name: first.name ?? c.name,
pushName: first.pushName ?? c.pushName,
isMyContact: first.isMyContact || c.isMyContact,
isBlocked: first.isBlocked || c.isBlocked,
}
: c,
);
}
return [...byId.values()];
}
async getContacts(): Promise<Contact[]> {
this.host.ensureReady();
let raw: RawWwebjsContact[];
let unreadable: number;
let firstError: string | undefined;
try {
// A direct in-page walk that yields so the liveness probe is not starved (see readLeanContacts,
// #1501), instead of whatsapp-web.js's atomic client.getContacts(). The projected rows are a
// strict subset of a Contact; the mapping below reads only those six fields.
const page = (this.client() as unknown as { pupPage?: { evaluate: <T>(fn: () => Promise<T>) => Promise<T> } })
.pupPage;
const read = await page?.evaluate(readLeanContacts);
raw = (read?.rows ?? []) as unknown as RawWwebjsContact[];
unreadable = read?.failed ?? 0;
firstError = read?.firstError;
} catch (error) {
rethrowIfNavigation(this.host, error);
// A dead page surfaces here as a raw Puppeteer error; convert it to the documented transport
// failure the way wwebjs-chats.ts does, so a transport death answers 503 instead of a bare 500.
if (this.host.isPageTransportError(error)) {
this.host.reportIfPageTransportError(error, 'getContacts');
throw new EngineTransportError('Transport died while reading contacts');
}
// A walk that outran the protocol budget got no answer: a 503, but no death.
if (isProtocolTimeout(error)) {
throw new EngineTransportError('WhatsApp Web did not answer the contact list read in time');
}
throw error;
}
// Read every id through readWid (so the `_serialized`->`$1` rename lands here too) and skip
// entries with no readable id, counted and logged like the chats path, rather than dropping
// the whole address book silently.
const contacts: Contact[] = [];
let skipped = 0;
for (const c of raw) {
const mapped = this.toContact(c);
if (!mapped) {
skipped++;
continue;
}
contacts.push(mapped);
}
// A systemic page failure (a renamed WA Web module, WWebJS not injected), not one unreadable
// entry: answer an error rather than a list a syncing consumer would read as every contact
// deleted. That covers models that exist but none mapped, and a failure that left only blocked
// contacts: getContactModel skips getAlternateUserWid for a blocked contact, so a blocked row
// still reads when that call is broken for everyone else.
if ((unreadable > 0 && !contacts.some(c => !c.isBlocked)) || (contacts.length === 0 && skipped > 0)) {
const reason =
`WhatsApp Web could not read any unblocked contact (${unreadable} failed, ${skipped} without an id, ` +
`${contacts.length} blocked read)${firstError ? `: ${firstError}` : ''}`;
// Nest does not log an HttpException and the contact service logs nothing, so this line is the
// only server-side trace of a page-wide failure.
this.host.logger.error(reason);
throw new InternalServerErrorException(reason);
}
if (skipped > 0) {
this.host.logger.warn(`Skipped ${skipped} contact(s) without a serialized id`);
}
if (unreadable > 0) {
this.host.logger.warn(`Skipped ${unreadable} contact(s) WhatsApp Web could not read`, { error: firstError });
}
return WwebjsContacts.mergeById(contacts);
}
async getContactById(contactId: string): Promise<Contact | null> {
this.host.ensureReady();
try {
const contact = await this.client().getContactById(contactId);
return this.toContact(contact);
} catch (error) {
rethrowIfNavigation(this.host, error);
// Unlike the avatar lookup, a throw here can legitimately mean the contact is absent:
// `window.WWebJS.getContact` has no try/catch and reads `contact.isBusiness` straight off
// `Contact.find`, so an unknown id throws a TypeError on null. Null (→ 404) stays the answer
// for that. A dead page is not a missing contact, though, and this was the one lookup that
// never separated the two.
if (this.host.isPageTransportError(error)) {
this.host.reportIfPageTransportError(error, 'getContactById');
throw new EngineTransportError(`Transport died while reading contact ${contactId}`);
}
// A command that outran the protocol budget got no answer either way: a 503, but no death.
if (isProtocolTimeout(error)) {
throw new EngineTransportError(`WhatsApp Web did not answer the read of contact ${contactId} in time`);
}
this.host.logger.warn(`Failed to get contact: ${contactId}`, { error: String(error) });
return null;
}
}
/**
* The lookup as WhatsApp Web answers it: `<lid>@lid` for a contact migrated to privacy-id addressing,
* else `<phone>@c.us`, or null when the number is not registered. The send path needs the `@lid`
* (see WwebjsMessaging.resolveSendId); {@link getNumberId} is the answer that crosses the engine boundary.
*/
async lookupNumberId(number: string): Promise<string | null> {
this.host.ensureReady();
const numberId = await withPage(this.host, 'getNumberId', () => this.client().getNumberId(number));
// Read both property names: a WA Web build that renamed `_serialized` would otherwise make
// every number look unregistered — and checkNumberExists below reports exactly that.
return readWid(numberId) ?? null;
}
async getNumberId(number: string): Promise<string | null> {
const wid = await this.lookupNumberId(number);
if (!wid?.endsWith('@lid')) return wid;
// The contract is the neutral `<phone>@c.us` WhatsApp holds for the account, which is what the Baileys
// engine answers. It can differ from the digits typed (a Brazilian, Mexican or Argentine number with or
// without its extra digit). A migrated contact's lookup names its `@lid`, the engine's own scheme, so the
// phone is read back through it. When WhatsApp Web knows none, the typed number stands in, and a send to
// it re-resolves to the lid. That read runs a second existence query when the page holds no phone for the
// lid, so its failure answers the typed number too: the lookup above already settled that the number
// exists. A session or page that died meanwhile still answers 409 or 503, as every read does.
const typed = `${userPart(number).replace(/\D/g, '')}@c.us`;
try {
const phone = await withPage(this.host, 'getNumberId', () => this.resolveContactPhone(wid));
return phone ? `${phone}@c.us` : typed;
} catch (error) {
if (error instanceof EngineNotReadyError || error instanceof EngineTransportError) throw error;
this.host.logger.debug('Could not read the phone of a migrated number, answering the typed number', {
error: String(error),
});
return typed;
}
}
async checkNumberExists(number: string): Promise<boolean> {
return (await this.lookupNumberId(number)) !== null;
}
async resolveContactPhone(contactId: string): Promise<string | null> {
this.host.ensureReady();
// Queried one id at a time: the batch form is prone to "Evaluation failed" and rate-limiting
// (whatsapp-web.js #3857/#3969). `pn` is the phone JID (`<digits>@c.us`) when the account knows
// the mapping. An empty/absent pn RESOLVES to null (a definitive "no mapping" answer); a thrown
// error PROPAGATES - the lid resolver must not mistake a transient failure (dead page,
// evaluation error, rate limit) for "this contact has no phone" and clobber a valid stored
// mapping with it. The HTTP route that promises null-on-failure swallows at its boundary
// (contact.service.resolveContactPhone).
const [result] = await this.client().getContactLidAndPhone([contactId]);
const pn = result?.pn;
return pn ? pn.replace(/@c\.us$/i, '').replace(/\D/g, '') || null : null;
}
async upsertContact(contactId: string, firstName: string, lastName = ''): Promise<void> {
this.host.ensureReady();
// wwjs addresses the addressbook entry by PHONE NUMBER, not JID (Client.js:3266). lastName is
// positional and required there, so an absent one is passed as an empty string rather than
// undefined, which would land in the page-side payload as the literal string "undefined".
// syncToAddressbook is left at its default (false): writing to the device addressbook is a
// heavier, separately-consented action than saving the WhatsApp contact.
await withPage(this.host, 'upsertContact', () =>
this.client().saveOrEditAddressbookContact(userPart(contactId), firstName, lastName),
);
this.host.logger.debug('Saved addressbook contact', { contactId });
}
async deleteContact(contactId: string): Promise<void> {
this.host.ensureReady();
await withPage(this.host, 'deleteContact', () => this.client().deleteAddressbookContact(userPart(contactId)));
this.host.logger.debug('Deleted addressbook contact', { contactId });
}
async blockContact(contactId: string): Promise<void> {
this.host.ensureReady();
await withPage(this.host, 'blockContact', async () => {
const contact = await this.client().getContactById(contactId);
await contact.block();
});
this.host.logger.debug('Blocked contact', { contactId });
}
/**
* The read half of block/unblockContact. Ids only — the neutral common subset with Baileys,
* whose blocklist query answers bare jids. An entry whose wid is unreadable (#747 rename
* hazard) is dropped rather than reported as the literal "undefined". A contact blocked under both
* its LID and its phone is two entries that read as one id, which is listed once.
*/
async getBlockedContacts(): Promise<string[]> {
this.host.ensureReady();
const contacts = await withPage(this.host, 'getBlockedContacts', () => this.client().getBlockedContacts());
const ids = contacts.map(c => readWid(c.id as unknown as SerializedWid)).filter((id): id is string => Boolean(id));
return [...new Set(ids)];
}
async unblockContact(contactId: string): Promise<void> {
this.host.ensureReady();
await withPage(this.host, 'unblockContact', async () => {
const contact = await this.client().getContactById(contactId);
await contact.unblock();
});
this.host.logger.debug('Unblocked contact', { contactId });
}
async getProfilePicture(contactId: string): Promise<string | null> {
this.host.ensureReady();
// WhatsApp Web keys a migrated contact's chat by its LID, so the lookup by a phone id can come back empty
// or fail where the LID answers (the Number Checker asks by the phone id its check returned). It is
// retried once by the LID the page holds; a dead or unanswering page is not retried, and a retry that
// gets nothing leaves the first outcome standing.
const byLid = parseWaId(contactId).kind === 'user';
let url: string | undefined;
try {
url = await this.client().getProfilePicUrl(contactId);
} catch (error) {
rethrowIfNavigation(this.host, error);
const pageDown = this.host.isPageTransportError(error) || isProtocolTimeout(error);
const viaLid = byLid && !pageDown ? await this.profilePictureByLid(contactId) : undefined;
if (viaLid) return viaLid;
// Nothing reaching here is a statement about the avatar, so nothing reaching here may become
// null. Returning null would answer 200 with {"url": null} — byte-identical to the verdict
// above — and a caller that caches "no avatar" would record absence for a lookup that never
// produced one. The page throws for two distinct reasons and we cannot tell them apart from
// the message: `getChat` failing to resolve the contact at all, or the profile-pic bridge
// failing. 404 would assert the first; 503 says only that we could not reach an answer, which
// is all we know.
//
// NOTE the Baileys adapter does the OPPOSITE on this same interface method, and correctly:
// there a no-picture verdict *is* delivered as a throw, so it swallows to null and uses its
// own deadline to separate a verdict from a non-answer. Do not harmonise the two into a shared
// helper — the engines disagree about what a throw means.
this.host.reportIfPageTransportError(error, 'getProfilePicture');
this.host.logger.warn(`Failed to get profile picture for ${contactId}: ${String(error)}`);
throw new EngineTransportError(`Could not read the profile picture for ${contactId}: ${String(error)}`);
}
return url || (byLid ? await this.profilePictureByLid(contactId) : undefined) || null;
}
/**
* The picture of a phone id looked up by the LID WhatsApp Web holds for it (no query is sent to find one),
* or undefined when there is no LID or that lookup also gets nothing. A session torn down meanwhile still
* answers 409: the client is taken through the readiness check before each page call.
*/
private async profilePictureByLid(phoneId: string): Promise<string | undefined> {
try {
const page = (
this.client() as unknown as { pupPage?: { evaluate: <T>(fn: (id: string) => T, id: string) => Promise<T> } }
).pupPage;
const lid = await page?.evaluate(readCurrentLid, phoneId);
if (!lid) return undefined;
return (await this.client().getProfilePicUrl(lid)) || undefined;
} catch (error) {
if (error instanceof EngineNotReadyError) throw error;
this.host.reportIfPageTransportError(error, 'getProfilePicture');
this.host.logger.debug('Could not read a profile picture by its LID', { error: String(error) });
return undefined;
}
}
}