Free, Open Source, Self-Hosted WhatsApp API Gateway
TypeScript apibotgatewayself-hostedwhatsappwhatsapp-apiwhatsapp-automationwhatsapp-botwhatsapp-gatewaywhatsapp-gateway-apiwhatsapp-webwhatsapp-web-api
import { Entity, PrimaryGeneratedColumn, Column, CreateDateColumn, Index, ValueTransformer } from 'typeorm';
import { jsonColumnType } from '../../../common/utils/column-types';
import { NulFreeTransformer } from '../../../common/transformers/nul-free.transformer';
/**
* A `bigint` column reads back as a string on PostgreSQL (pg avoids >2^53 precision loss) but as a
* number on SQLite. WhatsApp epoch-seconds are far below 2^53, so coerce reads to a number for a
* consistent REST/SDK/MCP contract (entity, DTO, the typed SDKs, and dashboard declare a numeric type).
* Writes pass through unchanged; null stays null.
*/
export const bigintToNumberTransformer: ValueTransformer = {
to: (value: number | null | undefined): number | null | undefined => value,
from: (value: string | number | null): number | null => {
if (value == null) return null;
const n = Number(value);
// Defensive: a bigint column can only return null or a numeric value, so NaN is unreachable —
// but coerce a hypothetical non-numeric read to null rather than leak NaN into the contract.
return Number.isNaN(n) ? null : n;
},
};
export enum MessageDirection {
INCOMING = 'incoming',
OUTGOING = 'outgoing',
}
export enum MessageStatus {
PENDING = 'pending',
SENT = 'sent',
DELIVERED = 'delivered',
READ = 'read',
FAILED = 'failed',
}
@Entity('messages')
@Index(['sessionId', 'createdAt'])
@Index(['chatId'])
// One chat's thread, paged newest-first, and its total; the send-pacing history probes filter on the
// same (sessionId, chatId, createdAt) prefix. The standalone chatId index stays for the search and
// stats reads that filter on chatId without a session. The explicit name matches the migration that
// creates it on synchronize-disabled deployments, so both schema paths converge on one index.
@Index('IDX_messages_sessionId_chatId_createdAt', ['sessionId', 'chatId', 'createdAt'])
// Explicit id tiebreaking keeps a message-time walk stable across SQLite and PostgreSQL.
@Index('IDX_messages_session_timestamp_id', ['sessionId', 'timestamp', 'id'])
@Index('IDX_messages_session_chat_timestamp_id', ['sessionId', 'chatId', 'timestamp', 'id'])
@Index('IDX_messages_session_direction_timestamp_id', ['sessionId', 'direction', 'timestamp', 'id'])
// Composite index for the ack-driven status UPDATE (scoped by sessionId + waMessageId).
// Without it every ack does a full table scan of a hot table.
@Index('UQ_messages_sessionId_waMessageId', ['sessionId', 'waMessageId'], { unique: true })
export class Message {
@PrimaryGeneratedColumn('uuid')
id!: string;
// No standalone @Index here: sessionId-only lookups are already served by the composite indexes
// that lead with sessionId: (sessionId, createdAt), (sessionId, chatId, createdAt) and the unique
// (sessionId, waMessageId).
@Column()
sessionId!: string;
@Column({ nullable: true })
waMessageId!: string;
@Column()
chatId!: string;
/** The sender's contact name (pushName) as the engine reported it: in a group that is the member, not
* the group. Null on legacy rows and on rows that carried no contact. */
@Column({ nullable: true, transformer: NulFreeTransformer })
chatName?: string;
/**
* Stable sender identity for a group, status or broadcast-list message: the JID who actually
* posted (`from` is the group, `status@broadcast` or list id; on Baileys a list message the account
* received is filed under the sender, so `from` is the sender too). Lets the chat view tell two
* same-named participants apart. Null on 1:1 messages, outgoing echoes, and legacy rows.
*/
@Column({ nullable: true })
author?: string;
@Column()
from!: string;
@Column()
to!: string;
@Column({ type: 'text', nullable: true, transformer: NulFreeTransformer })
body!: string;
@Column({ default: 'text' })
type!: string;
@Column({
type: 'varchar',
default: MessageDirection.OUTGOING,
})
direction!: MessageDirection;
@Column({ type: 'bigint', nullable: true, transformer: bigintToNumberTransformer })
timestamp!: number;
@Column({ type: jsonColumnType(), nullable: true })
metadata!: Record<string, unknown>;
/**
* Storage key of this message's archived media, or null when nothing was archived — which is the
* case for every row written while `CHAT_MEDIA_ARCHIVE_ENABLED` is off (the default), for non-media
* messages, and for media above the archive cap. Independent of the inline base64 copy in
* `metadata.media`, which stays inline by default and is replaced after verification in archive mode.
*/
// Partial index for the chat-media orphan sweep's per-chunk `mediaPath IN (...)` lookup. NULL for
// every un-archived row (archiving is opt-in), so the WHERE clause keeps the index to rows that
// can ever match. The explicit name matches the migration that creates it on synchronize-disabled
// deployments, so both schema paths converge on one index.
// The column name is QUOTED in the predicate on purpose: PostgreSQL folds a bare identifier to
// lower case, so `mediaPath IS NOT NULL` makes synchronize fail on `column "mediapath" does not
// exist`. The migration below already quotes it, so this is also what keeps the two in step.
@Index('IDX_messages_mediaPath', { where: '"mediaPath" IS NOT NULL' })
@Column({ nullable: true })
mediaPath?: string;
/** Mimetype of the archived media, so the read endpoint can serve a Content-Type without
* depending on the inline copy. Null whenever `mediaPath` is. */
@Column({ nullable: true, transformer: NulFreeTransformer })
mediaMimetype?: string;
@Column({
type: 'varchar',
default: MessageStatus.SENT,
})
@Index()
status!: MessageStatus;
// Standalone index for the createdAt-only range predicates of the stats aggregates — the
// composite above leads with sessionId, so it can't serve them (SQLite needs ANALYZE stats for
// a skip-scan; Postgres has none). The explicit name matches the migration that creates it on
// synchronize-disabled deployments, so both schema paths converge on one index.
@CreateDateColumn()
@Index('IDX_messages_createdAt')
createdAt!: Date;
}