Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

feat(webhooks): add chatId smart-filter field for per-chat scoping

krishshah99447838bf496a9b
diff --git a/README.md b/README.md
index ba2ff1776..de8c170ad 100644
--- a/README.md
+++ b/README.md
@@ -330,8 +330,10 @@ curl -X POST http://localhost:2785/api/sessions/{sessionId}/webhooks \
> **Smart filters (optional):** add a `filters` object to fire the webhook only when conditions match
> (AND), e.g. `{ "conditions": [{ "field": "sender", "operator": "is", "value": ["[email protected]"] }] }`.
-> Fields: `sender` / `recipient` / `body` / `type` / `mentions` / `fromMe` / `hasMedia` / `isGroup`. A
-> webhook with no filters behaves exactly as before. See the API specification for the full schema.
+> Fields: `sender` / `recipient` / `chatId` / `body` / `type` / `mentions` / `fromMe` / `hasMedia` /
+> `isGroup` / `kind`. A webhook with no filters behaves exactly as before. Use `chatId` to allowlist
+> specific groups or DMs (e.g. `{ "field": "chatId", "operator": "is", "value": ["120…@g.us"] }`).
+> See the API specification for the full schema.
## 🤖 MCP Server (AI Agents)
diff --git a/dashboard/src/components/FilterBuilder.tsx b/dashboard/src/components/FilterBuilder.tsx
index 2a7508574..7eaa891df 100644
--- a/dashboard/src/components/FilterBuilder.tsx
+++ b/dashboard/src/components/FilterBuilder.tsx
@@ -24,6 +24,7 @@ interface FieldDescriptor {
const MESSAGE_FIELDS: FieldDescriptor[] = [
{ field: 'sender', kind: 'id', operators: ['is', 'isNot'] },
{ field: 'recipient', kind: 'id', operators: ['is', 'isNot'] },
+ { field: 'chatId', kind: 'id', operators: ['is', 'isNot'] },
{ field: 'body', kind: 'text', operators: ['contains', 'equals'] },
{ field: 'type', kind: 'enum', operators: ['is', 'isNot'], enumValues: MESSAGE_TYPES },
{ field: 'isGroup', kind: 'boolean', operators: ['is'] },
diff --git a/dashboard/src/i18n/locales/ar.json b/dashboard/src/i18n/locales/ar.json
index 07f8176bf..28a124da3 100644
--- a/dashboard/src/i18n/locales/ar.json
+++ b/dashboard/src/i18n/locales/ar.json
@@ -447,6 +447,7 @@
"fields": {
"sender": "المُرسِل",
"recipient": "المُستلِم",
+ "chatId": "معرّف المحادثة",
"body": "نص الرسالة",
"type": "نوع الرسالة",
"isGroup": "محادثة جماعية",
diff --git a/dashboard/src/i18n/locales/de.json b/dashboard/src/i18n/locales/de.json
index f5a79dc3f..add33ad1c 100644
--- a/dashboard/src/i18n/locales/de.json
+++ b/dashboard/src/i18n/locales/de.json
@@ -432,6 +432,7 @@
"fields": {
"sender": "Absender",
"recipient": "Empfänger",
+ "chatId": "Chat-ID",
"body": "Nachrichteninhalt",
"type": "Nachrichtentyp",
"isGroup": "Ist Gruppenchat",
diff --git a/dashboard/src/i18n/locales/en.json b/dashboard/src/i18n/locales/en.json
index f4f705639..8d094a8ba 100644
--- a/dashboard/src/i18n/locales/en.json
+++ b/dashboard/src/i18n/locales/en.json
@@ -432,6 +432,7 @@
"fields": {
"sender": "Sender",
"recipient": "Recipient",
+ "chatId": "Chat ID",
"body": "Message body",
"type": "Message type",
"isGroup": "Is group chat",
diff --git a/dashboard/src/i18n/locales/es.json b/dashboard/src/i18n/locales/es.json
index 02c48f452..3887e2540 100644
--- a/dashboard/src/i18n/locales/es.json
+++ b/dashboard/src/i18n/locales/es.json
@@ -432,6 +432,7 @@
"fields": {
"sender": "Remitente",
"recipient": "Destinatario",
+ "chatId": "ID del chat",
"body": "Cuerpo del mensaje",
"type": "Tipo de mensaje",
"isGroup": "Es chat de grupo",
diff --git a/dashboard/src/i18n/locales/fr.json b/dashboard/src/i18n/locales/fr.json
index 839741e54..556f83471 100644
--- a/dashboard/src/i18n/locales/fr.json
+++ b/dashboard/src/i18n/locales/fr.json
@@ -432,6 +432,7 @@
"fields": {
"sender": "Expéditeur",
"recipient": "Destinataire",
+ "chatId": "ID du chat",
"body": "Corps du message",
"type": "Type de message",
"isGroup": "Est une discussion de groupe",
diff --git a/dashboard/src/i18n/locales/he.json b/dashboard/src/i18n/locales/he.json
index bf815b40f..c7e2a1325 100644
--- a/dashboard/src/i18n/locales/he.json
+++ b/dashboard/src/i18n/locales/he.json
@@ -441,6 +441,7 @@
"fields": {
"sender": "שולח",
"recipient": "נמען",
+ "chatId": "מזהה שיחה",
"body": "גוף ההודעה",
"type": "סוג הודעה",
"isGroup": "צ'אט קבוצתי",
diff --git a/dashboard/src/i18n/locales/it.json b/dashboard/src/i18n/locales/it.json
index 700948661..d130888c4 100644
--- a/dashboard/src/i18n/locales/it.json
+++ b/dashboard/src/i18n/locales/it.json
@@ -432,6 +432,7 @@
"fields": {
"sender": "Mittente",
"recipient": "Destinatario",
+ "chatId": "ID chat",
"body": "Corpo del messaggio",
"type": "Tipo di messaggio",
"isGroup": "È una chat di gruppo",
diff --git a/dashboard/src/i18n/locales/ko.json b/dashboard/src/i18n/locales/ko.json
index 78cb3d4b0..e1904ea78 100644
--- a/dashboard/src/i18n/locales/ko.json
+++ b/dashboard/src/i18n/locales/ko.json
@@ -432,6 +432,7 @@
"fields": {
"sender": "보낸 사람",
"recipient": "받는 사람",
+ "chatId": "채팅 ID",
"body": "메시지 본문",
"type": "메시지 유형",
"isGroup": "그룹 채팅 여부",
diff --git a/dashboard/src/i18n/locales/pt-BR.json b/dashboard/src/i18n/locales/pt-BR.json
index 99df78fda..065ced50a 100644
--- a/dashboard/src/i18n/locales/pt-BR.json
+++ b/dashboard/src/i18n/locales/pt-BR.json
@@ -432,6 +432,7 @@
"fields": {
"sender": "Remetente",
"recipient": "Destinatário",
+ "chatId": "ID do chat",
"body": "Corpo da mensagem",
"type": "Tipo de mensagem",
"isGroup": "É chat de grupo",
diff --git a/dashboard/src/i18n/locales/te.json b/dashboard/src/i18n/locales/te.json
index f79c6b941..36aed521f 100644
--- a/dashboard/src/i18n/locales/te.json
+++ b/dashboard/src/i18n/locales/te.json
@@ -432,6 +432,7 @@
"fields": {
"sender": "పంపినవారు",
"recipient": "స్వీకర్త",
+ "chatId": "చాట్ ID",
"body": "సందేశ విషయం",
"type": "సందేశ రకం",
"isGroup": "గ్రూప్ చాట్",
diff --git a/dashboard/src/i18n/locales/tr.json b/dashboard/src/i18n/locales/tr.json
index 192263890..178571bfe 100644
--- a/dashboard/src/i18n/locales/tr.json
+++ b/dashboard/src/i18n/locales/tr.json
@@ -432,6 +432,7 @@
"fields": {
"sender": "Gönderen",
"recipient": "Alıcı",
+ "chatId": "Sohbet kimliği",
"body": "Mesaj içeriği",
"type": "Mesaj türü",
"isGroup": "Grup sohbeti mi",
diff --git a/dashboard/src/i18n/locales/zh-CN.json b/dashboard/src/i18n/locales/zh-CN.json
index 7f544081f..7e042e0fe 100644
--- a/dashboard/src/i18n/locales/zh-CN.json
+++ b/dashboard/src/i18n/locales/zh-CN.json
@@ -432,6 +432,7 @@
"fields": {
"sender": "发送者",
"recipient": "接收者",
+ "chatId": "聊天 ID",
"body": "消息正文",
"type": "消息类型",
"isGroup": "是群聊",
diff --git a/dashboard/src/i18n/locales/zh-HK.json b/dashboard/src/i18n/locales/zh-HK.json
index 67d131bcd..f493fe5e0 100644
--- a/dashboard/src/i18n/locales/zh-HK.json
+++ b/dashboard/src/i18n/locales/zh-HK.json
@@ -432,6 +432,7 @@
"fields": {
"sender": "傳送者",
"recipient": "接收者",
+ "chatId": "聊天 ID",
"body": "訊息內容",
"type": "訊息類型",
"isGroup": "是群組聊天",
diff --git a/docs/06-api-specification.md b/docs/06-api-specification.md
index d2b1f9306..f38a3383c 100644
--- a/docs/06-api-specification.md
+++ b/docs/06-api-specification.md
@@ -4543,7 +4543,7 @@ Create a webhook for the session.
| events | string[] | no | `@IsArray`, `@ArrayMinSize(1)`, `@IsIn([...WEBHOOK_EVENTS, '*'], { each: true })` | Event names to subscribe to (see allowed set above). Defaults to `["message.received"]` when omitted. |
| secret | string | no | `@IsString`, `@MinLength(16)`, `@MaxLength(255)` | HMAC-SHA256 signing key. **Write-only** — never returned by a webhook route (not returned by `GET /api/infra/export-data` either). Used for `X-OpenWA-Signature`. Defaults to `null`. |
| headers | Record<string,string> | no | `@IsHeaderMap()` — flat object (not array), ≤50 entries, names match `/^[A-Za-z0-9-]+$/`, values are strings ≤1024 chars with no C0 control/DEL (CR/LF injection guard). | Custom headers added to deliveries. **Write-only** — never returned by a webhook route (not returned by `GET /api/infra/export-data` either). At delivery, `content-type` and `x-openwa-*` names are stripped. Defaults to `{}`. |
-| filters | WebhookFilters \| null | no | `@IsValidWebhookFilters()` — `{ conditions: [...] }`; each condition `{ field, operator('is'\|'isNot'\|'contains'\|'equals'), value(string\|string[]\|boolean), caseSensitive?:boolean }`; bounds: max 20 conditions, 100 values/condition, 1000-char text values. Message fields: `sender`, `recipient`, `body`, `type`, `isGroup`, `fromMe`, `hasMedia`, `mentions`. | Optional AND pre-filter; **all** conditions must match for the webhook to fire. Omit/null = fire on every subscribed event. Defaults to `null`. ⚠️ A condition whose field is DEFINED for the event family but absent from that event's payload cannot match, so it suppresses the event entirely (a field with no definition for the family is skipped instead, and does not suppress) — `message.ack`/`message.failed` carry `{ id, messageId, status, ack }` and `message.reaction` carries `{ messageId, chatId, reaction, senderId }`, none of which has a sender or body, so a `sender` filter silently drops all three. Scope the subscription with `events[]` rather than relying on a filter to be inert. Set `LOG_LEVEL=debug` to see each suppression and the payload fields that were available. |
+| filters | WebhookFilters \| null | no | `@IsValidWebhookFilters()` — `{ conditions: [...] }`; each condition `{ field, operator('is'\|'isNot'\|'contains'\|'equals'), value(string\|string[]\|boolean), caseSensitive?:boolean }`; bounds: max 20 conditions, 100 values/condition, 1000-char text values. Message fields: `sender`, `recipient`, `chatId`, `body`, `type`, `isGroup`, `kind`, `fromMe`, `hasMedia`, `mentions`. | Optional AND pre-filter; **all** conditions must match for the webhook to fire. Omit/null = fire on every subscribed event. Defaults to `null`. ⚠️ A condition whose field is DEFINED for the event family but absent from that event's payload cannot match, so it suppresses the event entirely (a field with no definition for the family is skipped instead, and does not suppress) — `message.ack`/`message.failed` carry `{ id, messageId, status, ack }` and `message.reaction` carries `{ messageId, chatId, reaction, senderId }`, none of which has a sender or body, so a `sender` filter silently drops all three. Scope the subscription with `events[]` rather than relying on a filter to be inert. Set `LOG_LEVEL=debug` to see each suppression and the payload fields that were available. |
| retryCount | number (int) | no | `@IsInt`, `@Min(0)`, `@Max(5)` | Delivery retry attempts on failure. Defaults to `3`. |
```json
@@ -6449,7 +6449,7 @@ and plugin vetoes apply to it like any other outbound message. Evaluation is fir
the receive path and runs at most once per message (engine re-fires are deduplicated).
`conditions` uses the **webhook filter format** (`message` family — see 6.4.8): a flat AND list of
-conditions over `sender`, `recipient`, `body`, `type`, `isGroup`, `fromMe`, `hasMedia`, `mentions`.
+conditions over `sender`, `recipient`, `chatId`, `body`, `type`, `isGroup`, `kind`, `fromMe`, `hasMedia`, `mentions`.
Omitted or empty conditions match every inbound message.
Loop safety: a rule never answers the account's own (`fromMe`) messages, messages older than
diff --git a/docs/07-api-collection.md b/docs/07-api-collection.md
index cf3d49ca3..77148aa19 100644
--- a/docs/07-api-collection.md
+++ b/docs/07-api-collection.md
@@ -1160,7 +1160,7 @@ curl -X POST "$BASE/api/sessions/$SESSION_ID/webhooks" \
"headers": { "X-Custom-Header": "value" },
"filters": {
"conditions": [
- { "field": "sender", "operator": "is", "value": ["[email protected]"] },
+ { "field": "chatId", "operator": "is", "value": ["[email protected]"] },
{ "field": "body", "operator": "contains", "value": "invoice" }
]
},
diff --git a/src/modules/webhook/filters/filter-evaluator.spec.ts b/src/modules/webhook/filters/filter-evaluator.spec.ts
index c86dc990f..ac0814dc7 100644
--- a/src/modules/webhook/filters/filter-evaluator.spec.ts
+++ b/src/modules/webhook/filters/filter-evaluator.spec.ts
@@ -195,6 +195,40 @@ describe('evaluateFilters', () => {
});
});
+ describe('chatId (conversation scoping so a webhook can allowlist specific groups)', () => {
+ it('matches an explicit chatId on the payload', () => {
+ const f = filters({ field: 'chatId', operator: 'is', value: ['[email protected]'] });
+ expect(evaluateFilters(f, 'message.received', msg({ chatId: '[email protected]', from: '[email protected]' }))).toBe(true);
+ expect(evaluateFilters(f, 'message.received', msg({ chatId: '[email protected]', from: '[email protected]' }))).toBe(false);
+ });
+
+ it('falls back to from when chatId is omitted (inbound group shape)', () => {
+ const f = filters({ field: 'chatId', operator: 'is', value: ['[email protected]'] });
+ expect(
+ evaluateFilters(f, 'message.received', msg({ from: '[email protected]', author: '[email protected]', isGroup: true })),
+ ).toBe(true);
+ expect(
+ evaluateFilters(f, 'message.received', msg({ from: '[email protected]', author: '[email protected]', isGroup: true })),
+ ).toBe(false);
+ });
+
+ it('supports isNot and multi-value allowlists', () => {
+ const allow = filters({ field: 'chatId', operator: 'is', value: ['[email protected]', '[email protected]'] });
+ expect(evaluateFilters(allow, 'message.received', msg({ chatId: '[email protected]' }))).toBe(true);
+ expect(evaluateFilters(allow, 'message.received', msg({ chatId: '[email protected]' }))).toBe(false);
+
+ const deny = filters({ field: 'chatId', operator: 'isNot', value: ['[email protected]'] });
+ expect(evaluateFilters(deny, 'message.received', msg({ chatId: '[email protected]' }))).toBe(false);
+ expect(evaluateFilters(deny, 'message.received', msg({ chatId: '[email protected]' }))).toBe(true);
+ });
+
+ it('scopes message.revoked / edited payloads that only carry chatId', () => {
+ const f = filters({ field: 'chatId', operator: 'is', value: ['[email protected]'] });
+ expect(evaluateFilters(f, 'message.revoked', { chatId: '[email protected]' })).toBe(true);
+ expect(evaluateFilters(f, 'message.edited', { chatId: '[email protected]', body: 'x' })).toBe(false);
+ });
+ });
+
describe('kind (chat kind, so a channel can be singled out where isGroup cannot)', () => {
// The reporter's case: a webhook subscribed to message.received also gets channel posts, and
// isGroup=false cannot tell a channel from a 1:1 chat. `kind` rides the received payload.
diff --git a/src/modules/webhook/filters/filter-types.ts b/src/modules/webhook/filters/filter-types.ts
index 8a1e1656b..a5380cdef 100644
--- a/src/modules/webhook/filters/filter-types.ts
+++ b/src/modules/webhook/filters/filter-types.ts
@@ -99,6 +99,15 @@ export const FILTER_FIELDS: Record<string, FieldDefinition[]> = {
operators: ID_OPERATORS,
resolve: data => str(data.to),
},
+ {
+ // Conversation JID (DM or group). Prefer the explicit chatId carried on received /
+ // edited / reaction / revoked payloads; fall back to `from` for older shapes where
+ // the chat is only on that field (inbound group messages often use [email protected]).
+ field: 'chatId',
+ kind: 'id',
+ operators: ID_OPERATORS,
+ resolve: data => str(data.chatId) ?? str(data.from),
+ },
{
field: 'body',
kind: 'text',