From 55870b88bfc26a0e7f73e76f63f31ec39224b86d Mon Sep 17 00:00:00 2001
From: devlikepro <waha@devlike.pro>
Date: Tue, 3 Mar 2026 14:33:10 +0700
Subject: [PATCH] [core] @Activity

---
 AGENTS.md                                    | 37 ++++++++++++++++++++
 src/core/engines/gows/session.gows.core.ts   |  2 ++
 src/core/engines/noweb/session.noweb.core.ts |  2 ++
 src/core/engines/webjs/session.webjs.core.ts |  2 ++
 4 files changed, 43 insertions(+)

diff --git a/AGENTS.md b/AGENTS.md
index 37a3d8ce..12a7c7a2 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -142,3 +142,40 @@ You can find related source code in the following paths:
 
 Following this playbook keeps contributions aligned with WAHA’s structure,
 automation hooks, and release process.
+
+## How to run API
+
+You can run the project outside of sandbox using the below command, then run
+queries against `default` session (if not asked to do something different) using
+`curl` and `X-Api-Key: 666` header.
+
+```bash
+export DEBUG=1
+export WAHA_API_KEY=666
+export WAHA_DASHBOARD_PASSWORD=666
+export WAHA_DASHBOARD_USERNAME=admin
+export WWHATSAPP_SWAGGER_USERNAME=admin
+export WHATSAPP_SWAGGER_PASSWORD=666
+export WHATSAPP_DEFAULT_ENGINE={WEBJS|WPP|NOWEB|GOWS}
+export WAHA_DEBUG_MODE=True
+export WAHA_HTTP_STRICT_MODE=1
+export WAHA_MEDIA_STORAGE=LOCAL
+export WHATSAPP_FILES_FOLDER=./.media
+
+npm run start
+```
+
+- Ask user before running the server.
+- Before executing some queries make sure the session is in `WORKING` status.
+- If it's `FAILED` or `SCAN_QR_CODE` ask user to scan QR code or fix failed
+  session.
+
+## Code
+
+### @Activity Decorator and Presence Tracking
+
+Add `@Activity()` (from `src/core/abc/activity.ts`) to every engine method that
+makes a network call to WhatsApp servers. It triggers `maintainPresenceOnline()`
+before the method runs, keeping the session ONLINE during API activity and
+scheduling an OFFLINE transition after an idle period. Skip it on methods that
+only throw `NotImplementedByEngineError` / `AvailableInPlusVersion`.
diff --git a/src/core/engines/gows/session.gows.core.ts b/src/core/engines/gows/session.gows.core.ts
index 3f6523a7..5009ac7e 100644
--- a/src/core/engines/gows/session.gows.core.ts
+++ b/src/core/engines/gows/session.gows.core.ts
@@ -916,6 +916,7 @@ export class WhatsappSessionGoWSCore extends WhatsappSession {
     return data.id;
   }
 
+  @Activity()
   async rejectCall(from: string, id: string): Promise<void> {
     const request = new messages.RejectCallRequest({
       session: this.session,
@@ -1079,6 +1080,7 @@ export class WhatsappSessionGoWSCore extends WhatsappSession {
     };
   }
 
+  @Activity()
   async checkNumberStatus(
     request: CheckNumberStatusQuery,
   ): Promise<WANumberExistResult> {
diff --git a/src/core/engines/noweb/session.noweb.core.ts b/src/core/engines/noweb/session.noweb.core.ts
index 713a2be4..922de47a 100644
--- a/src/core/engines/noweb/session.noweb.core.ts
+++ b/src/core/engines/noweb/session.noweb.core.ts
@@ -908,6 +908,7 @@ export class WhatsappSessionNoWebCore extends WhatsappSession {
   /**
    * Other methods
    */
+  @Activity()
   async checkNumberStatus(
     request: CheckNumberStatusQuery,
   ): Promise<WANumberExistResult> {
@@ -927,6 +928,7 @@ export class WhatsappSessionNoWebCore extends WhatsappSession {
     return this.generateMessageID();
   }
 
+  @Activity()
   async rejectCall(from: string, id: string): Promise<void> {
     const jid = toJID(this.ensureSuffix(from));
     await this.sock.rejectCall(id, jid);
diff --git a/src/core/engines/webjs/session.webjs.core.ts b/src/core/engines/webjs/session.webjs.core.ts
index 237151bd..d2023f7f 100644
--- a/src/core/engines/webjs/session.webjs.core.ts
+++ b/src/core/engines/webjs/session.webjs.core.ts
@@ -694,6 +694,7 @@ export class WhatsappSessionWebJSCore extends WhatsappSession {
     return screenshot as Buffer;
   }
 
+  @Activity()
   async checkNumberStatus(
     request: CheckNumberStatusQuery,
   ): Promise<WANumberExistResult> {
@@ -737,6 +738,7 @@ export class WhatsappSessionWebJSCore extends WhatsappSession {
   /**
    * Other methods
    */
+  @Activity()
   async rejectCall(from: string, id: string): Promise<void> {
     const peerJid = normalizeJid(this.ensureSuffix(from));
     const call = new CallInstance(this.whatsapp, null);