Free, Open Source, Self-Hosted WhatsApp API Gateway
TypeScript apibotgatewayself-hostedwhatsappwhatsapp-apiwhatsapp-automationwhatsapp-botwhatsapp-gatewaywhatsapp-gateway-apiwhatsapp-webwhatsapp-web-api
import { BadRequestException, Injectable, NotFoundException, Optional } from '@nestjs/common';
import { ModuleRef } from '@nestjs/core';
import { ConfigService } from '@nestjs/config';
import { InjectRepository } from '@nestjs/typeorm';
import { Repository } from 'typeorm';
import { createLogger } from '../../common/services/logger.service';
import { LidMappingStoreService } from '../../engine/identity/lid-mapping-store.service';
import { chatKind } from '../../engine/identity/wa-id';
import { evaluateFilters, prepareFilterLidResolver } from '../webhook/filters/filter-evaluator';
import { PLUGIN_MESSAGE_PORT, type PluginMessagePort } from '../../core/plugins/plugin-host-ports';
import { AutomationRule } from './entities/automation-rule.entity';
import { Session } from '../session/entities/session.entity';
import {
AUTOMATION_COOLDOWN_MAX_SECONDS,
CreateAutomationRuleDto,
UpdateAutomationRuleDto,
} from './dto/automation-rule.dto';
/**
* The cooldown map is swept of entries older than the longest allowed cooldown once it reaches this
* size, and after a sweep only once it doubles again, so a sweep that frees nothing is not repeated
* on every reply.
*/
const COOLDOWN_SWEEP_THRESHOLD = 10_000;
/**
* Messages older than this never get an automated answer. A reconnect replays the offline-queued
* backlog through the same inbound path; answering it would burst-reply every stale message — and
* it is the unbounded arm of an autoreply-vs-autoreply loop, where each side answers the other's
* queued message only after its own cooldown has long expired.
*/
const MAX_MESSAGE_AGE_SECONDS = 300;
/**
* Chat kinds a rule answers only when it names them. A reply into a channel is published to every
* follower when the account is an admin there, and is refused everywhere else (a failed send that can
* also count toward the send-pacing breaker); a status or broadcast list has no conversation to answer.
*/
const OPT_IN_CHAT_KINDS: ReadonlySet<string> = new Set(['channel', 'broadcast', 'status']);
/**
* Single-message autoreply rules: evaluated on every inbound message, first matching rule replies
* into the chat through the ordinary send path.
*
* The reply is sent via the plugin message port (bound to `MessageService.sendText` by
* MessageModule), which the module graph cannot inject directly: `MessageModule` imports
* `SessionModule`, and this module is imported BY `SessionModule` (the projector calls
* `evaluateInbound`), so a constructor dependency here would close a module cycle.
* `ModuleRef.get(..., { strict: false })` resolves the core-owned token lazily at first use
* instead. In unit contexts without a ModuleRef the evaluator logs and skips.
*/
@Injectable()
export class AutomationRulesService {
private readonly logger = createLogger('AutomationRulesService');
/**
* `${ruleId}:${chatId}` -> when the rule last fired in that chat. The quiet period is judged against
* the rule's CURRENT cooldownSeconds, so an edit takes effect on a window already running; the sweep
* only drops an entry older than the longest cooldown a rule may have. Per-process.
*/
private readonly cooldowns = new Map<string, number>();
private nextCooldownSweepAt = COOLDOWN_SWEEP_THRESHOLD;
private messagePort?: PluginMessagePort;
constructor(
@InjectRepository(AutomationRule, 'data')
private readonly ruleRepository: Repository<AutomationRule>,
@InjectRepository(Session, 'data')
private readonly sessionRepository: Repository<Session>,
@Optional()
private readonly moduleRef?: ModuleRef,
@Optional()
private readonly lidMappingStore?: LidMappingStoreService,
@Optional()
private readonly configService?: ConfigService,
) {}
async create(sessionId: string, dto: CreateAutomationRuleDto): Promise<AutomationRule> {
// The automation_rules.sessionId FK turns a missing session into a driver error (500) at save
// time; check first so the caller gets a truthful 404, as the webhook create route does.
if (!(await this.sessionRepository.exists({ where: { id: sessionId } }))) {
throw new NotFoundException(`Session with id '${sessionId}' not found`);
}
// Per-session cap, the same shape (and softness) the webhook fan-out cap has: every inbound
// message is evaluated against every rule of its session, so an unbounded count turns each
// message into unbounded work. A concurrent create can race the count — the cap bounds
// amplification, it is not an invariant. Rules already above it are left alone.
const maxPerSession = this.configService?.get<number>('automation.maxPerSession', 32) ?? 32;
if (maxPerSession > 0) {
const existing = await this.ruleRepository.count({ where: { sessionId } });
if (existing >= maxPerSession) {
throw new BadRequestException(
`Automation rule limit reached for this session (${existing}/${maxPerSession}); delete one before adding another`,
);
}
}
const rule = this.ruleRepository.create({
sessionId,
name: dto.name,
replyText: dto.replyText,
conditions: dto.conditions ?? null,
cooldownSeconds: dto.cooldownSeconds ?? 60,
enabled: dto.enabled ?? true,
});
// No transaction of its own: on SQLite's single shared connection the rollback of a foreign key failure (the
// session deleted since the check above) would discard what other callers wrote while it was open.
return this.ruleRepository.save(rule, { transaction: false });
}
async findAll(sessionId: string): Promise<AutomationRule[]> {
// id is the tiebreak: createdAt has 1-second precision on SQLite, so rules created together
// would otherwise have an unstable order — and order here IS the evaluation order.
return this.ruleRepository.find({ where: { sessionId }, order: { createdAt: 'ASC', id: 'ASC' } });
}
async findOne(sessionId: string, id: string): Promise<AutomationRule> {
const rule = await this.ruleRepository.findOne({ where: { id, sessionId } });
if (!rule) {
throw new NotFoundException(`Automation rule ${id} not found`);
}
return rule;
}
async update(sessionId: string, id: string, dto: UpdateAutomationRuleDto): Promise<AutomationRule> {
const rule = await this.findOne(sessionId, id);
const patch: Partial<Pick<AutomationRule, 'name' | 'replyText' | 'conditions' | 'cooldownSeconds' | 'enabled'>> =
{};
if (dto.name !== undefined) patch.name = dto.name;
if (dto.replyText !== undefined) patch.replyText = dto.replyText;
if (dto.conditions !== undefined) patch.conditions = dto.conditions;
if (dto.cooldownSeconds !== undefined) patch.cooldownSeconds = dto.cooldownSeconds;
if (dto.enabled !== undefined) patch.enabled = dto.enabled;
if (Object.keys(patch).length === 0) return rule;
// A conditional UPDATE of the carried fields, not save() of the entity read above: save() would
// write back stale values of every column this request did not touch (switching a rule off could
// be undone by an overlapping edit) and re-insert a rule a concurrent DELETE removed.
const result = await this.ruleRepository.update({ id, sessionId }, patch);
if (!result.affected) throw new NotFoundException(`Automation rule ${id} not found`);
return this.findOne(sessionId, id);
}
async remove(sessionId: string, id: string): Promise<void> {
const rule = await this.findOne(sessionId, id);
await this.ruleRepository.remove(rule);
}
/**
* Evaluate one inbound message against the session's rules; first match replies.
*
* Called fire-and-forget from the projector's dispatch stage, which runs at most once per inbound
* message (the UNIQUE(sessionId, waMessageId) insert oracle) — so a rule sees no engine re-fires.
* Everything here must swallow its own failures: a broken rule, a dead DB or a refused send must
* never surface into the receive path.
*
* `fromMe` is guarded HERE because the inbound path does not filter it — some engine deliveries
* carry the account's own messages, and answering yourself is the shortest possible reply loop.
*/
async evaluateInbound(sessionId: string, message: Record<string, unknown>): Promise<void> {
if (message.fromMe === true) return;
const chatId = typeof message.chatId === 'string' ? message.chatId : null;
if (!chatId) return;
// Freshness gate (see MAX_MESSAGE_AGE_SECONDS). A missing timestamp counts as fresh — losing
// one legitimate reply to a mapper quirk is worse than answering a possibly old message once.
const timestamp = typeof message.timestamp === 'number' ? message.timestamp : null;
if (timestamp !== null && Date.now() / 1000 - timestamp > MAX_MESSAGE_AGE_SECONDS) return;
let rules: AutomationRule[];
try {
rules = await this.ruleRepository.find({
where: { sessionId, enabled: true },
order: { createdAt: 'ASC', id: 'ASC' },
});
} catch (error) {
this.logger.warn('Automation rule lookup failed', {
sessionId,
error: error instanceof Error ? error.message : String(error),
});
return;
}
if (rules.length === 0) return;
const resolveLid = await prepareFilterLidResolver(
rules.map(rule => rule.conditions),
'message.received',
message,
this.lidMappingStore ? lids => this.lidMappingStore!.phonesForLidsPersisted(lids) : undefined,
);
// Resolved the way the `kind` filter field resolves it, so the guard and a kind condition agree.
const kind = typeof message.kind === 'string' && message.kind ? message.kind : chatKind(chatId);
const optInOnly = OPT_IN_CHAT_KINDS.has(kind);
// First match wins: one inbound message never produces more than one automated reply, and rule
// order (creation order) is the tiebreak the operator can reason about. A rule without a `kind`
// condition skips the opt-in chat kinds; naming the kind is how a rule reaches them. A rule whose
// stored conditions are malformed (a restore bypasses the DTO) is skipped on its own, so it cannot
// silence every other rule of the session. A `conditions` that is not a plain object, or a
// non-array `conditions.conditions`, is refused explicitly: evaluateFilters reads either as "no
// filter", which would answer every inbound message.
const rule = rules.find(candidate => {
try {
const conditions: unknown = candidate.conditions;
if (
conditions != null &&
(typeof conditions !== 'object' ||
Array.isArray(conditions) ||
(candidate.conditions?.conditions != null && !Array.isArray(candidate.conditions.conditions)))
) {
throw new TypeError('conditions must be an object with a conditions array');
}
return (
(!optInOnly || candidate.conditions?.conditions?.some(c => c.field === 'kind')) &&
evaluateFilters(candidate.conditions, 'message.received', message, resolveLid)
);
} catch (error) {
this.logger.warn('Skipping automation rule with malformed conditions', {
sessionId,
ruleId: candidate.id,
error: error instanceof Error ? error.message : String(error),
});
return false;
}
});
if (!rule) return;
if (this.inCooldown(rule, chatId)) return;
// Enter the cooldown BEFORE the send: a burst of matching messages must collapse to one reply
// even while the first send is still in flight.
this.enterCooldown(rule, chatId);
try {
const messagePort = this.resolveMessagePort();
if (!messagePort) return;
await messagePort.sendText(sessionId, { chatId, text: rule.replyText });
this.logger.debug('Automation rule replied', { sessionId, ruleId: rule.id, chatId });
} catch (error) {
// The send path already persisted/audited its own failure; here it only must not propagate.
this.logger.warn('Automation rule reply failed', {
sessionId,
ruleId: rule.id,
chatId,
error: error instanceof Error ? error.message : String(error),
});
}
}
private resolveMessagePort(): PluginMessagePort | undefined {
if (!this.messagePort) {
try {
// The core-owned port token, resolved lazily — never a static import of MessageService: a
// value-import here closes the file cycle session (projector) -> automation -> message ->
// session, and whichever class evaluates last in that cycle is `undefined` while Nest builds
// the graph. By reply time every module is loaded, so resolving the token lazily sidesteps
// the cycle entirely.
this.messagePort = this.moduleRef?.get<typeof PLUGIN_MESSAGE_PORT, PluginMessagePort>(PLUGIN_MESSAGE_PORT, {
strict: false,
});
} catch (error) {
this.logger.warn('MessageService is not resolvable; automation replies are disabled', {
error: error instanceof Error ? error.message : String(error),
});
return undefined;
}
}
return this.messagePort;
}
private inCooldown(rule: AutomationRule, chatId: string): boolean {
if (!rule.cooldownSeconds) return false;
const firedAt = this.cooldowns.get(`${rule.id}:${chatId}`);
return firedAt !== undefined && firedAt + rule.cooldownSeconds * 1000 > Date.now();
}
private enterCooldown(rule: AutomationRule, chatId: string): void {
if (!rule.cooldownSeconds) return;
const now = Date.now();
if (this.cooldowns.size >= this.nextCooldownSweepAt) {
for (const [key, firedAt] of this.cooldowns) {
if (firedAt + AUTOMATION_COOLDOWN_MAX_SECONDS * 1000 <= now) this.cooldowns.delete(key);
}
this.nextCooldownSweepAt = Math.max(COOLDOWN_SWEEP_THRESHOLD, this.cooldowns.size * 2);
}
this.cooldowns.set(`${rule.id}:${chatId}`, now);
}
}