Free, Open Source, Self-Hosted WhatsApp API Gateway
TypeScript apibotgatewayself-hostedwhatsappwhatsapp-apiwhatsapp-automationwhatsapp-botwhatsapp-gatewaywhatsapp-gateway-apiwhatsapp-webwhatsapp-web-api
import { randomUUID, createHash } from 'crypto';
/**
* Safely convert an unknown value to a string for use in idempotency keys
*/
function toStr(value: unknown, fallback = 'unknown'): string {
if (value === null || value === undefined) return fallback;
if (typeof value === 'string') return value;
if (typeof value === 'number' || typeof value === 'boolean') return String(value);
return fallback;
}
/**
* Generate a short hash from data for use in idempotency keys.
* Used when no unique identifier is available in the payload.
*/
function hashData(data: Record<string, unknown>): string {
const str = JSON.stringify(data, Object.keys(data).sort());
return createHash('sha256').update(str).digest('hex').substring(0, 12);
}
/**
* Generate an idempotency key based on event type and data.
* Same event with same data will produce the same key (deterministic).
*
* @remarks
* Stable message keys are content-based (keyed on the unique message id), so two deliveries of the
* same logical message dedupe. Recurring events (message edits/reactions and session lifecycle
* transitions) can repeat with identical content, so they are salted with `occurrenceId` (minted ONCE
* per dispatch and reused across retries): distinct occurrences get distinct keys while retries of
* the same occurrence stay stable.
*
* @param occurrenceId - Unique id minted once per dispatch; salts recurring occurrence keys.
*/
export function generateIdempotencyKey(event: string, data: Record<string, unknown>, occurrenceId?: string): string {
// Only recurring occurrence keys consume this salt; stable message and QR keys ignore it.
const occurrence = occurrenceId ? `_${occurrenceId}` : '';
switch (event) {
case 'message.received':
case 'message.sent':
// Dispatched payload is an IncomingMessage, which carries `id`; fall back to a legacy `messageId`.
// Resolve the value before toStr() β toStr() returns a truthy 'unknown' fallback, so chaining with
// `||` would short-circuit before reaching the second field.
// Scope by sessionId: waMessageIds are unique per account, not globally, so two
// sessions could otherwise collide on the same key and wrongly dedupe each other's events.
return `msg_${toStr(data.sessionId)}_${toStr(data.id ?? data.messageId)}`;
case 'message.ack':
// Message ID + delivery status together are unique. Key on the neutral `status`; fall back to
// the legacy `ack` integer for backward compatibility with older payloads.
return `ack_${toStr(data.sessionId)}_${toStr(data.id ?? data.messageId)}_${toStr(data.status ?? data.ack, '0')}`;
case 'message.receipt':
// One receipt per recipient and status: the participant keeps two members' `read` apart.
return `receipt_${toStr(data.sessionId)}_${toStr(data.id ?? data.messageId)}_${toStr(data.participant)}_${toStr(data.status)}`;
case 'message.failed':
return `failed_${toStr(data.sessionId)}_${toStr(data.id ?? data.messageId)}_${toStr(data.status ?? data.ack, '0')}`;
case 'message.revoked':
return `rev_${toStr(data.sessionId)}_${toStr(data.id ?? data.messageId)}`;
case 'message.edited':
// Editing the same message multiple times should produce different idempotency keys.
// Salt with occurrenceId (minted once per dispatch, reused across retries) so distinct occurrences
// get distinct keys, while retries of the same delivery stay stable.
return `edit_${toStr(data.sessionId)}_${toStr(data.messageId)}${occurrence}`;
case 'message.reaction':
// A reaction carries no unique id and is a read-modify-write of the message's reactions map; the
// same sender can re-apply the same emoji over time (π β remove β π). Keying on
// (sender, target message) alone would collapse a genuine re-reaction onto the earlier one, so salt
// with occurrenceId (minted once per dispatch, reused across retries): distinct occurrences get
// distinct keys while retries of the same delivery stay stable.
return `react_${toStr(data.sessionId)}_${toStr(data.messageId)}_${toStr(data.senderId)}${occurrence}`;
case 'session.status':
// Salted so repeated transitions to the same status (e.g. across disconnect/reconnect cycles)
// stay distinct instead of collapsing onto one key.
return `sess_${toStr(data.sessionId)}_${toStr(data.status)}${occurrence}`;
case 'session.qr':
// QR changes each time, use the QR data hash for uniqueness
return `qr_${toStr(data.sessionId)}_${hashData({ qr: data.qr })}`;
case 'session.authenticated':
// Salted so each (re)authentication is a distinct event β phone/pushName repeat across reconnects.
return `auth_${toStr(data.sessionId)}_${hashData(data)}${occurrence}`;
case 'session.disconnected':
// Salted so repeat disconnects stay distinct β `reason` alone can be a constant (Baileys
// always sends 'logged out'), which would otherwise collapse every disconnect onto one key.
return `disc_${toStr(data.sessionId)}_${hashData({ reason: data.reason })}${occurrence}`;
case 'session.reconnect_loop':
// Salted per occurrence: once the backoff hits its cap, a later outage that loops to the same
// attempt count produces a byte-identical payload, and that second alert must not collapse
// onto the first at the receiver or in the outbox and failure tables.
return `loop_${toStr(data.sessionId)}_${toStr(data.attempts)}${occurrence}`;
case 'session.restriction':
// Keyed on what changed (`kind` is null when a restriction is lifted) and salted per
// occurrence: an account that is restricted, freed and restricted again for the same cause
// produces the same content twice, and the second one is genuine news that must not collapse
// onto the first. Without an explicit case the default branch hashes the whole payload, which
// would dedupe exactly that.
return `restr_${toStr(data.sessionId)}_${toStr(data.kind)}_${toStr(data.active)}${occurrence}`;
case 'call.accepted':
case 'call.rejected':
case 'call.missed':
// A call id is unique per call and each call ends exactly once, so (session, call, outcome)
// is already distinct β no occurrence salt, matching call.received's stable key.
return `call_${toStr(data.sessionId)}_${toStr(data.callId)}_${toStr(data.outcome)}`;
case 'event.response':
// Each RSVP is its own message with its own id, and a changed answer is a new RSVP with a new
// id, so (session, RSVP id) is already unique per occurrence and stable across retries.
return `rsvp_${toStr(data.sessionId)}_${toStr(data.responseMessageId)}`;
case 'poll.vote':
// A vote carries no id of its own, but each change of a voter's selection is stamped by the
// voter's clock in milliseconds, so (session, poll, voter, timestampMs) is distinct per change and
// stable across retries. The selection is hashed in as well, and the whole second stays the
// fallback for a payload without the millisecond stamp: a voter flipping A, B, A within one second
// would otherwise send the third change under the key of the first, and a receiver that dedupes on
// the key would end on B.
return `vote_${toStr(data.sessionId)}_${toStr(data.pollMessageId)}_${toStr(data.voterId)}_${toStr(data.timestampMs ?? data.timestamp)}_${hashData({ selectedOptions: data.selectedOptions ?? null })}`;
case 'presence.update':
// Keyed on the chat and salted per occurrence. Only genuine state CHANGES are dispatched, and
// a contact who types, stops, and types again produces the same payload each time β content
// hashing would collapse that back into one delivery and hide the very transitions the event
// exists to report. The participants are hashed in as well: two group members changing state
// in the same millisecond are two events and must not share a key. Pre-stringified for the
// same reason as group.update below.
return `pres_${toStr(data.sessionId)}_${toStr(data.chatId)}_${hashData({ participants: JSON.stringify(data.participants ?? null) })}${occurrence}`;
case 'group.join':
// A membership change carries no unique id and repeats with identical content (the same user
// leaves and rejoins the same group). Key on the affected participants and salt with
// occurrenceId (minted once per dispatch, reused across retries) so a genuine re-join is not
// deduped onto the earlier delivery.
return `grp_${toStr(data.groupId)}_${hashData({ participants: data.participantIds })}_join${occurrence}`;
case 'group.leave':
// Same recurring-occurrence treatment as group.join.
return `grp_${toStr(data.groupId)}_${hashData({ participants: data.participantIds })}_leave${occurrence}`;
case 'group.join_request':
// Same recurring-occurrence treatment as group.join: a user whose request was rejected can
// legitimately ask again, so the occurrence salt keeps the re-request deliverable.
return `grp_${toStr(data.groupId)}_${hashData({ participants: data.participantIds })}_join_request${occurrence}`;
case 'group.update':
// Key on WHAT changed (a subject set to "X" twice is one logical change; announce toggling
// back and forth is several), salted per occurrence so identical repeat updates stay distinct.
// `changes` is pre-stringified: hashData's allowlist replacer only keeps TOP-LEVEL keys, so a
// nested object would serialize as {} and hash every distinct change identically.
return `grp_${toStr(data.groupId)}_update_${hashData({ changes: JSON.stringify(data.changes ?? null) })}${occurrence}`;
case 'call.received':
// A call id is unique per call, so keying on (session, callId) gives each occurrence a
// distinct key with no occurrenceId salt, while retries of the same dispatch regenerate the
// same key (same stability contract as the message.* keys). Scoped by sessionId like `msg_`.
return `call_${toStr(data.sessionId)}_${toStr(data.callId)}`;
default:
// Fallback: hash entire payload for determinism
return `evt_${event.replace(/\./g, '_')}_${hashData(data)}`;
}
}
/**
* Generate a unique delivery ID for each webhook delivery (stable across retry attempts)
*/
export function generateDeliveryId(): string {
return `dlv_${randomUUID()}`;
}