fix(NOWEB): template message with image header — hasMedia:true but download fails - fix #2275

closes #2260
Co-authored-by: ropu <rovagnati@gmail.com>

.dockerignore

@@ -1,5 +1,9 @@
+tmp/*
 Dockerfile
+docker-compose
+src/core/engines/gows/proto
 .*sessions
+sessions
 files
 venv
 .wwebjs_auth
@@ -7,6 +11,8 @@ docs
 examples
 .github
 .git
+.envs/*
+.env
 
 # compiled output
 /dist

.env.example

@@ -0,0 +1,159 @@
+# WAHA - WhatsApp HTTP API
+#
+# https://waha.devlike.pro/docs/how-to/config/
+#
+
+# ====================
+# ===== SECURITY =====
+# ====================
+WAHA_API_KEY=00000000000000000000000000000000
+WAHA_DASHBOARD_USERNAME=admin
+WAHA_DASHBOARD_PASSWORD=11111111111111111111111111111111
+WHATSAPP_SWAGGER_USERNAME=admin
+WHATSAPP_SWAGGER_PASSWORD=11111111111111111111111111111111
+
+# Disable Dashboard or Swagger
+WAHA_DASHBOARD_ENABLED=True
+WHATSAPP_SWAGGER_ENABLED=True
+
+# ==================
+# ===== COMMON =====
+# ==================
+# WhatsApp engine (WEBJS is default, GOWS or NOWEB for better performance)
+WHATSAPP_DEFAULT_ENGINE=WEBJS
+# So you don't have to create sessions/apps when switching between engines
+WAHA_NAMESPACE=all
+
+# "Firefox (YourApp)" in Linked Devices
+# WAHA_CLIENT_DEVICE_NAME=YourApp
+
+# Base URL for the API (used for webhooks, file URLs, etc.)
+WAHA_BASE_URL=http://localhost:3000
+# WAHA_PUBLIC_URL=http://localhost:3000
+
+# Server configuration (if you need to customize hostname/port)
+# WHATSAPP_API_SCHEMA=http
+# WHATSAPP_API_PORT=3000
+# WHATSAPP_API_HOSTNAME=localhost
+
+
+# ===================
+# ====== GOWS =======
+# ===================
+# By default, GOWS uses cgo (libc) DNS resolver
+# You can ask to use golang one, but it's less reliable
+# GODEBUG=netdns=go
+
+# ===================
+# ===== LOGGING =====
+# ===================
+# Log format: JSON (for log management systems) or PRETTY (for development)
+WAHA_LOG_FORMAT=JSON
+
+# Log level: info, debug, error, warn
+WAHA_LOG_LEVEL=info
+
+# Don't print QR codes in logs
+WAHA_PRINT_QR=False
+
+# ======================
+# ===== PROMETHEUS =====
+# ======================
+# Prometheus metrics endpoint - GET /metrics
+# WAHA_PROMETHEUS_ENABLED=True
+# WAHA_PROMETHEUS_PATH=/metrics
+# WAHA_PROMETHEUS_METRIC_PREFIX=waha_
+# WAHA_PROMETHEUS_HTTP_DURATION_BUCKETS=0.005,0.01,0.025,0.05,0.1,0.25,0.5,1,2.5,5,10,30
+# Events to count in waha_events_total ('*' for all) - the server actively processes listed events even with no webhooks
+# WAHA_PROMETHEUS_TRACK_EVENTS=message.any
+# Optional basic auth for the metrics endpoint (both must be set)
+# WAHA_PROMETHEUS_USERNAME=admin
+# WAHA_PROMETHEUS_PASSWORD=secret
+
+# =========================
+# ===== MEDIA STORAGE =====
+# =========================
+# Local storage (default)
+WAHA_MEDIA_STORAGE=LOCAL
+WHATSAPP_FILES_LIFETIME=0
+WHATSAPP_FILES_FOLDER=/app/.media
+
+#
+# Media download settings
+#
+# Events (webhooks, websockets)
+# WAHA_EVENTS_DOWNLOAD_MEDIA=true
+# WAHA_EVENTS_DOWNLOAD_MEDIA_MIMETYPES=image/jpeg,image/png
+# API default behavior (GET /api/{session}/chats/{chatId}/messages, etc.)
+# WAHA_API_DOWNLOAD_MEDIA=true
+# WAHA_API_DOWNLOAD_MEDIA_MIMETYPES=image/jpeg,image/png
+
+# DEPRECATED - use WAHA_EVENTS_* and WAHA_API_* variables above
+# WHATSAPP_DOWNLOAD_MEDIA=true
+# WHATSAPP_FILES_MIMETYPES=image/jpeg,image/png
+
+# S3 storage (uncomment to use)
+# WAHA_MEDIA_STORAGE=S3
+# WAHA_S3_REGION=eu-west-2
+# WAHA_S3_BUCKET=waha
+# WAHA_S3_ACCESS_KEY_ID=minioadmin
+# WAHA_S3_SECRET_ACCESS_KEY=minioadmin
+# WAHA_S3_ENDPOINT=http://minio:9000
+# WAHA_S3_FORCE_PATH_STYLE=True
+# WAHA_S3_PROXY_FILES=True
+
+# PostgreSQL storage (uncomment to use)
+# WAHA_MEDIA_STORAGE=POSTGRESQL
+# WAHA_MEDIA_POSTGRESQL_URL=postgres://postgres:postgres@postgres:5432/postgres?sslmode=disable
+
+# ===========================
+# ===== SESSION STORAGE =====
+# ===========================
+# PostgreSQL for sessions (uncomment to use)
+# WHATSAPP_SESSIONS_POSTGRESQL_URL=postgres://postgres:postgres@postgres:5432/postgres?sslmode=disable
+
+# MongoDB for sessions (uncomment to use)
+# WHATSAPP_SESSIONS_MONGO_URL=mongodb://mongouser:mongopassword@mongodb:27017
+
+# =================
+# ===== APPS ======
+# =================
+# WAHA_APPS_ENABLED=True
+# REDIS_URL=redis://:redis@redis:6379
+
+# Apps Jobs configuration - *_AGE in seconds
+# WAHA_APPS_JOBS_REMOVE_ON_COMPLETE_AGE=
+# WAHA_APPS_JOBS_REMOVE_ON_COMPLETE_COUNT=
+# WAHA_APPS_JOBS_REMOVE_ON_FAIL_AGE=
+# WAHA_APPS_JOBS_REMOVE_ON_FAIL_COUNT
+
+
+# ==================================
+# ===== ADVANCED CONFIGURATION =====
+# ==================================
+
+# Timezone for screenshots and logs
+# TZ=Europe/Dublin
+
+# Session management
+# WHATSAPP_START_SESSION=session1,session2
+# WHATSAPP_RESTART_ALL_SESSIONS=False
+
+# Webhooks
+# WHATSAPP_HOOK_URL=https://webhook.site/11111111-1111-1111-1111-11111111
+# WHATSAPP_HOOK_CUSTOM_HEADERS=custom_header_key:custom_header_value
+# WHATSAPP_HOOK_EVENTS=session.status,message,message.reaction
+
+# Proxy configuration
+# WHATSAPP_PROXY_SERVER=proxy.example.com:3128
+# WHATSAPP_PROXY_SERVER_USERNAME=user
+# WHATSAPP_PROXY_SERVER_PASSWORD=pass
+
+# HTTPS configuration
+# !DEPRECATED!
+# Setup nginx reverse proxy to handle TLS connection
+# using Let's encrypt or self-issued certificate
+# WAHA_HTTPS_ENABLED=true
+# WAHA_HTTPS_PATH_KEY=/etc/letsencrypt/live/waha.example.pro/privkey.pem
+# WAHA_HTTPS_PATH_CERT=/etc/letsencrypt/live/waha.example.pro/cert.pem
+# WAHA_HTTPS_PATH_CA=/etc/letsencrypt/live/waha.example.pro/chain.pem

.env.yarn

@@ -0,0 +1 @@
+SHARP_IGNORE_GLOBAL_LIBVIPS=1

.eslintignore

@@ -0,0 +1,3 @@
+src/core/engines/gows/grpc/*
+src/core/engines/gows/proto/*
+src/core/engines/webjs/_lodash.js

.eslintrc.js

@@ -1,36 +0,0 @@
-module.exports = {
-  parser: '@typescript-eslint/parser',
-  parserOptions: {
-    project: 'tsconfig.json',
-    sourceType: 'module',
-  },
-  plugins: ['@typescript-eslint/eslint-plugin', 'simple-import-sort'],
-  extends: [
-    'plugin:@typescript-eslint/eslint-recommended',
-    'plugin:@typescript-eslint/recommended',
-    'prettier',
-    'prettier/@typescript-eslint',
-  ],
-  root: true,
-  env: {
-    node: true,
-    jest: true,
-  },
-  rules: {
-    'simple-import-sort/imports': 'error',
-    'simple-import-sort/exports': 'error',
-    '@typescript-eslint/interface-name-prefix': 'off',
-    '@typescript-eslint/explicit-function-return-type': 'off',
-    '@typescript-eslint/explicit-module-boundary-types': 'off',
-    '@typescript-eslint/no-inferrable-types': 'off',
-    '@typescript-eslint/no-explicit-any': 'off',
-    '@typescript-eslint/ban-ts-ignore': 'off',
-    '@typescript-eslint/ban-ts-comment': 'off',
-    '@typescript-eslint/no-unused-vars': 'off',
-    'lines-between-class-members': [
-      'error',
-      'always',
-      { exceptAfterSingleLine: true },
-    ],
-  },
-};

.github/ISSUE_TEMPLATE/bug_report.md

@@ -1,30 +1,34 @@
 ---
 name: Bug report
 about: Create a report to help us improve
-title: '[BUG][WEBJS] - '
+title: '[WEBJS] - '
 labels: bug
 assignees: ''
+type: 'BUG'
 ---
 
-**Describe the bug**
+### Describe the bug
 
-> A clear and concise description of what the bug is. Feel free to remove
-> sections that you don't feel to make the text shorter!
+A clear and concise description of what the bug is. Feel free to remove sections
+that you don't feel to make the text shorter!
 
-**Version**
+### Version
+
+Get the WAHA version by calling `GET /api/version`
 
 ```json
 {
-  "version": "2023.11.1",
-  "engine": "NOWEB",
-  "tier": "PLUS",
-  "browser": "/usr/bin/google-chrome-stable"
+  "version": "YYYY.MM.DD",
+  "engine": "ENGINE",
+  "tier": "TIER"
 }
 ```
 
-> You can get the WAHA version by calling `GET /api/version` Try to update to
-> [the latest version](https://github.com/devlikeapro/waha/releases) before
-> creating an issue!
+Try to update to
+[the latest version](https://github.com/devlikeapro/waha/releases) before
+creating an issue!
+
+## Steps
 
 **To Reproduce** Steps to reproduce the behavior:
 
@@ -33,29 +37,23 @@ assignees: ''
 3. Scroll down to '....'
 4. See error
 
-**Expected behavior**
+### Expected behavior
 
-> A clear and concise description of what you expected to happen.
+A clear and concise description of what you expected to happen.
 
-**Engine** I'm using **WEBJS** engine.
+### Requests - Responses
 
-> If you set `WHATSAPP_DEFAULT_ENGINE` explicitly to
-> [one of the engine](https://waha.devlike.pro/docs/how-to/engines/) - please
-> provide that information here and in the issue title.
+Please attach all sent requests, responses that you sent.
 
-**Requests - Responses**
+### Docker Logs
 
-> Please attach all sent requests, responses that you sent.
+Collect and attach related docker logs if you have any
+https://waha.devlike.pro/docs/how-to/deploy/#viewing-the-logs
 
-**Docker Logs**
+### Screenshots
 
-> Collect and attach related docker logs if you have any
-> https://waha.devlike.pro/docs/how-to/deploy/#viewing-the-logs
+If applicable, add screenshots to help explain your problem.
 
-**Screenshots**
+### Additional context
 
-> If applicable, add screenshots to help explain your problem.
-
-**Additional context**
-
-> Add any other context about the problem here.
+Add any other context about the problem here.

.github/ISSUE_TEMPLATE/feature_request.md

@@ -1,24 +1,25 @@
 ---
 name: Feature request
 about: Suggest an idea for this project
-title: '[Feature Request]'
+title: ''
 labels: ''
 assignees: ''
+type: 'Feature'
 ---
 
 **Is your feature request related to a problem? Please describe.** I'm always
 frustrated when [...]
 
-> A clear and concise description of what the problem is. Ex.
+A clear and concise description of what the problem is. Ex.
 
 **Describe the solution you'd like**
 
-> A clear and concise description of what you want to happen.
+A clear and concise description of what you want to happen.
 
 **Describe alternatives you've considered**
 
-> A clear and concise description of any alternative solutions or features
-> you've considered.
+A clear and concise description of any alternative solutions or features you've
+considered.
 
 **Additional context** Add any other context or screenshots about the feature
 request here.

.github/ISSUE_TEMPLATE/question.md

@@ -0,0 +1,11 @@
+---
+name: Question
+about: I have a question about the project or feature
+title: '[Question] '
+labels: 'question'
+assignees: ''
+---
+
+👉 Kindly use
+[GitHub Discussions](https://github.com/devlikeapro/waha/discussions) to ask
+questions!

.github/workflows/build.yaml

@@ -8,38 +8,75 @@ on:
 jobs:
   docker-build:
     runs-on: ${{ matrix.runner }}
-    name: ${{ matrix.platform }} - ${{ matrix.browser }} - ${{ matrix.tag }}
+    name:
+      ${{ matrix.engine }} - ${{ matrix.browser }} - ${{ matrix.platform }} -
+      ${{ matrix.tag }}
     strategy:
+      fail-fast: false
       matrix:
         include:
-          # Chromium
-          - runner: 'buildjet-4vcpu-ubuntu-2204'
+          # Chromium - x86
+          - runner: 'ubuntu-latest'
             tag: 'latest'
             platform: 'amd64'
             browser: 'chromium'
-          - runner: 'buildjet-4vcpu-ubuntu-2204-arm'
+            engine: 'WEBJS'
+            goss: 'goss-linux-amd64'
+
+          # Chromium - ARM
+          - runner: 'ubuntu-24.04-arm'
             tag: 'arm'
             platform: 'linux/arm64'
             browser: 'chromium'
-          # Chrome
-          - runner: 'buildjet-4vcpu-ubuntu-2204'
+            engine: 'WEBJS'
+            goss: 'goss-linux-arm'
+
+          # Chrome - x86
+          - runner: 'ubuntu-latest'
             tag: 'chrome'
             platform: 'amd64'
             browser: 'chrome'
-          # Chrome is not supported on arm64
-          #          - runner: "buildjet-4vcpu-ubuntu-2204-arm"
-          #            tag: "chrome-arm"
-          #            platform: "linux/arm64"
-          #            browser: "chrome"
-          # No browser
-          - runner: 'buildjet-4vcpu-ubuntu-2204'
+            engine: 'WEBJS'
+            goss: 'goss-linux-amd64'
+
+          # Chrome - ARM (Chrome is not available for ARM)
+          #- runner: "ubuntu-24.04-arm"
+          #  tag: "chrome-arm"
+          #  platform: "linux/arm64"
+          #  browser: "chrome"
+          #  goss: 'goss-linux-arm'
+
+          # NOWEB - x86
+          - runner: 'ubuntu-latest'
             tag: 'noweb'
             platform: 'amd64'
             browser: 'none'
-          - runner: 'buildjet-4vcpu-ubuntu-2204-arm'
+            engine: 'NOWEB'
+            goss: 'goss-linux-amd64'
+
+          # NOWEB - ARM
+          - runner: 'ubuntu-24.04-arm'
             tag: 'noweb-arm'
             platform: 'linux/arm64'
             browser: 'none'
+            engine: 'NOWEB'
+            goss: 'goss-linux-arm'
+
+          # GOWS - x86
+          - runner: 'ubuntu-latest'
+            tag: 'gows'
+            platform: 'amd64'
+            browser: 'none'
+            engine: 'GOWS'
+            goss: 'goss-linux-amd64'
+
+          # No browser - ARM
+          - runner: 'ubuntu-24.04-arm'
+            tag: 'gows-arm'
+            platform: 'linux/arm64'
+            browser: 'none'
+            engine: 'GOWS'
+            goss: 'goss-linux-arm'
 
     steps:
       - name: Checkout
@@ -64,7 +101,9 @@ jobs:
           username: ${{ secrets.DOCKER_USER }}
           password: ${{ secrets.DOCKER_TOKEN }}
 
-      - name: Build and push
+      - name: Build (attempt 1)
+        id: build1
+        continue-on-error: true
         uses: docker/build-push-action@v4
         with:
           context: .
@@ -72,6 +111,86 @@ jobs:
           platforms: ${{ matrix.platform }}
           build-args: |
             USE_BROWSER=${{ matrix.browser }}
+            WHATSAPP_DEFAULT_ENGINE=${{ matrix.engine }}
+          push: false
+          load: true
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}
+
+      - name: Wait to retry build
+        if: steps.build1.outcome == 'failure'
+        run: |
+          sleep 10
+
+      - name: Build (attempt 2)
+        id: build2
+        if: steps.build1.outcome == 'failure'
+        continue-on-error: true
+        uses: docker/build-push-action@v4
+        with:
+          context: .
+          file: Dockerfile
+          platforms: ${{ matrix.platform }}
+          build-args: |
+            USE_BROWSER=${{ matrix.browser }}
+            WHATSAPP_DEFAULT_ENGINE=${{ matrix.engine }}
+          push: false
+          load: true
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}
+
+      - name: Wait to retry build
+        if: steps.build2.outcome == 'failure'
+        run: |
+          sleep 10
+
+      - name: Build (attempt 3)
+        if: steps.build2.outcome == 'failure'
+        uses: docker/build-push-action@v4
+        with:
+          context: .
+          file: Dockerfile
+          platforms: ${{ matrix.platform }}
+          build-args: |
+            USE_BROWSER=${{ matrix.browser }}
+            WHATSAPP_DEFAULT_ENGINE=${{ matrix.engine }}
+          push: false
+          load: true
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}
+
+      - name: Install goss
+        env:
+          GOSS_DOWNLOAD: 'https://github.com/goss-org/goss/releases/download'
+          GOSS_VERSION: 'v0.4.8'
+        run: |
+          curl -L https://github.com/goss-org/goss/releases/download/${{ env.GOSS_VERSION }}/${{ matrix.goss }} -o /usr/local/bin/goss
+          chmod +rx /usr/local/bin/goss
+
+      - name: Run smoke tests
+        working-directory: tests/smoke
+        timeout-minutes: 2
+        run: |
+          docker run -d \
+            --name smoke \
+            --rm -p3000:3000 \
+            -e WAHA_API_KEY=test \
+            ${{ vars.DOCKER_IMAGE }}:${{ matrix.tag }}
+
+          sleep 3
+          docker logs smoke
+          goss validate --retry-timeout 30s --sleep 1s
+          docker rm --force smoke
+
+      - name: Push
+        uses: docker/build-push-action@v4
+        with:
+          context: .
+          file: Dockerfile
+          platforms: ${{ matrix.platform }}
+          build-args: |
+            USE_BROWSER=${{ matrix.browser }}
+            WHATSAPP_DEFAULT_ENGINE=${{ matrix.engine }}
           push: ${{ github.ref_type == 'tag' }}
           tags: ${{ steps.meta.outputs.tags }}
           labels: ${{ steps.meta.outputs.labels }}

.github/workflows/dev.yaml

@@ -0,0 +1,220 @@
+name: Dev
+
+on:
+  schedule:
+    - cron: '0 0 * * *'
+  workflow_dispatch:
+
+jobs:
+  #  unit-tests:
+  #    if: github.repository == 'devlikeapro/waha-plus'
+  #    runs-on: ubuntu-22.04
+  #    name: Unit tests
+  #    steps:
+  #      - name: Checkout
+  #        uses: actions/checkout@v4
+  #        with:
+  #          fetch-depth: 0
+  #
+  #      - name: Set up Node
+  #        uses: actions/setup-node@v4
+  #        with:
+  #          node-version: 22
+  #
+  #      - name: Enable Corepack
+  #        run: |
+  #          corepack enable
+  #          corepack prepare yarn@4.9.2 --activate
+  #
+  #      - name: Install dependencies
+  #        run: |
+  #          unset GIT_CONFIG_PARAMETERS
+  #          yarn install --immutable
+  #
+  #      - name: Run unit tests
+  #        run: yarn test:unit
+
+  docker-build:
+    if: github.repository == 'devlikeapro/waha'
+    #    needs: unit-tests
+    runs-on: ${{ matrix.runner }}
+    name:
+      ${{ matrix.engine }} - ${{ matrix.browser }} - ${{ matrix.platform }} -
+      ${{ matrix.tag }}
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          # Chromium - x86
+          - runner: 'ubuntu-latest'
+            tag: 'dev'
+            platform: 'amd64'
+            browser: 'chromium'
+            engine: 'WEBJS'
+            goss: 'goss-linux-amd64'
+
+          # Chrome - x86
+          - runner: 'ubuntu-latest'
+            tag: 'dev-chrome'
+            platform: 'amd64'
+            browser: 'chrome'
+            engine: 'WEBJS'
+            goss: 'goss-linux-amd64'
+
+          # Chromium - ARM
+          - runner: 'ubuntu-24.04-arm'
+            tag: 'dev-arm'
+            platform: 'linux/arm64'
+            browser: 'chromium'
+            engine: 'WEBJS'
+            goss: 'goss-linux-arm'
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v3
+        with:
+          ref: dev
+          fetch-depth: 0
+
+      - name: Check recent changes
+        id: recent
+        run: |
+          count=$(git rev-list --after="24 hours ago" --count HEAD || true)
+          if [ "$count" -gt 0 ]; then
+            echo "has_recent=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "has_recent=false" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: No recent changes summary
+        if: ${{ steps.recent.outputs.has_recent != 'true' }}
+        run:
+          echo "No commits in the last 24 hours; skipping build." >>
+          "$GITHUB_STEP_SUMMARY"
+
+      - name: Set up Docker Buildx
+        if: ${{ steps.recent.outputs.has_recent == 'true' }}
+        uses: docker/setup-buildx-action@v2
+
+      - name: Docker meta
+        if: ${{ steps.recent.outputs.has_recent == 'true' }}
+        id: meta
+        uses: docker/metadata-action@v4
+        with:
+          images: ${{ vars.DOCKER_IMAGE }}
+          flavor: latest=false
+          tags: |
+            type=raw,value=${{ matrix.tag }}
+
+      - name: Login to image repository
+        if: ${{ steps.recent.outputs.has_recent == 'true' }}
+        uses: docker/login-action@v2
+        with:
+          username: ${{ secrets.DOCKER_USER }}
+          password: ${{ secrets.DOCKER_TOKEN }}
+
+      - name: Build (attempt 1)
+        id: build1
+        if: ${{ steps.recent.outputs.has_recent == 'true' }}
+        continue-on-error: true
+        uses: docker/build-push-action@v4
+        with:
+          context: .
+          file: Dockerfile
+          platforms: ${{ matrix.platform }}
+          build-args: |
+            USE_BROWSER=${{ matrix.browser }}
+            WHATSAPP_DEFAULT_ENGINE=${{ matrix.engine }}
+          push: false
+          load: true
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}
+
+      - name: Wait to retry build
+        if:
+          ${{ steps.recent.outputs.has_recent == 'true' && steps.build1.outcome
+          == 'failure' }}
+        run: |
+          sleep 10
+
+      - name: Build (attempt 2)
+        id: build2
+        if:
+          ${{ steps.recent.outputs.has_recent == 'true' && steps.build1.outcome
+          == 'failure' }}
+        continue-on-error: true
+        uses: docker/build-push-action@v4
+        with:
+          context: .
+          file: Dockerfile
+          platforms: ${{ matrix.platform }}
+          build-args: |
+            USE_BROWSER=${{ matrix.browser }}
+            WHATSAPP_DEFAULT_ENGINE=${{ matrix.engine }}
+          push: false
+          load: true
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}
+
+      - name: Wait to retry build
+        if:
+          ${{ steps.recent.outputs.has_recent == 'true' && steps.build2.outcome
+          == 'failure' }}
+        run: |
+          sleep 10
+
+      - name: Build (attempt 3)
+        if:
+          ${{ steps.recent.outputs.has_recent == 'true' && steps.build2.outcome
+          == 'failure' }}
+        uses: docker/build-push-action@v4
+        with:
+          context: .
+          file: Dockerfile
+          platforms: ${{ matrix.platform }}
+          build-args: |
+            USE_BROWSER=${{ matrix.browser }}
+            WHATSAPP_DEFAULT_ENGINE=${{ matrix.engine }}
+          push: false
+          load: true
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}
+
+      - name: Install goss
+        if: ${{ steps.recent.outputs.has_recent == 'true' }}
+        env:
+          GOSS_DOWNLOAD: 'https://github.com/goss-org/goss/releases/download'
+          GOSS_VERSION: 'v0.4.8'
+        run: |
+          curl -L https://github.com/goss-org/goss/releases/download/${{ env.GOSS_VERSION }}/${{ matrix.goss }} -o /usr/local/bin/goss
+          chmod +rx /usr/local/bin/goss
+
+      - name: Run smoke tests
+        if: ${{ steps.recent.outputs.has_recent == 'true' }}
+        working-directory: tests/smoke
+        timeout-minutes: 2
+        run: |
+          docker run -d \
+            --name smoke \
+            --rm -p3000:3000 \
+            -e WAHA_API_KEY=test \
+            ${{ vars.DOCKER_IMAGE }}:${{ matrix.tag }}
+
+          sleep 3
+          docker logs smoke
+          goss validate --retry-timeout 30s --sleep 1s
+          docker rm --force smoke
+
+      - name: Push
+        if: ${{ steps.recent.outputs.has_recent == 'true' }}
+        uses: docker/build-push-action@v4
+        with:
+          context: .
+          file: Dockerfile
+          platforms: ${{ matrix.platform }}
+          build-args: |
+            USE_BROWSER=${{ matrix.browser }}
+            WHATSAPP_DEFAULT_ENGINE=${{ matrix.engine }}
+          push: true
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}

.github/workflows/github-translate.yml

@@ -0,0 +1,51 @@
+name: 'github-translate'
+on:
+  issues:
+    types: [opened]
+  issue_comment:
+    types: [created]
+  discussion:
+    types: [created]
+  discussion_comment:
+    types: [created]
+  # pull_request_target:
+  #   types: [opened, edited]
+  # pull_request_review_comment:
+  #   types: [created, edited]
+
+jobs:
+  en:
+    if: github.repository == 'devlikeapro/waha'
+    permissions:
+      issues: write
+      discussions: write
+      pull-requests: write
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: devlikeapro/github-translate-action@main
+        env:
+          # GITHUB_TOKEN: ${{ secrets.GH_TOKEN }}
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        with:
+          IS_MODIFY_TITLE: true
+          CUSTOM_BOT_NOTE: 'English'
+          TARGET_LANGUAGE: 'eng'
+          TRANSLATED_LANGUAGE: 'en'
+#  pt:
+#    permissions:
+#      issues: write
+#      discussions: write
+#      pull-requests: write
+#    runs-on: ubuntu-latest
+#    steps:
+#      - uses: actions/checkout@v4
+#      - uses: devlikeapro/github-translate-action@main
+#        env:
+#          # GITHUB_TOKEN: ${{ secrets.GH_TOKEN }}
+#          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+#        with:
+#          IS_MODIFY_TITLE: false
+#          CUSTOM_BOT_NOTE: 'Portuguese'
+#          TARGET_LANGUAGE: 'por'
+#          TRANSLATED_LANGUAGE: 'pt'

.github/workflows/manual-push.yaml

@@ -1,84 +0,0 @@
-name: Manual push
-
-on:
-  workflow_dispatch:
-    inputs:
-      tag:
-        description: 'Tag to push'
-        required: true
-        default: 'dev'
-      push:
-        description: 'Push to registry'
-        required: true
-        type: boolean
-        default: true
-
-jobs:
-  docker-build:
-    runs-on: ${{ matrix.runner }}
-    name: ${{ matrix.platform }} - ${{ matrix.browser }} - ${{ matrix.tag }}
-    strategy:
-      matrix:
-        include:
-          # Chromium
-          - runner: 'buildjet-4vcpu-ubuntu-2204'
-            tag: 'latest'
-            platform: 'amd64'
-            browser: 'chromium'
-          - runner: 'buildjet-4vcpu-ubuntu-2204-arm'
-            tag: 'arm'
-            platform: 'linux/arm64'
-            browser: 'chromium'
-          # Chrome
-          - runner: 'buildjet-4vcpu-ubuntu-2204'
-            tag: 'chrome'
-            platform: 'amd64'
-            browser: 'chrome'
-          # Chrome is not supported on arm64
-          #          - runner: "buildjet-4vcpu-ubuntu-2204-arm"
-          #            tag: "chrome-arm"
-          #            platform: "linux/arm64"
-          #            browser: "chrome"
-          # No browser
-          - runner: 'buildjet-4vcpu-ubuntu-2204'
-            tag: 'noweb'
-            platform: 'amd64'
-            browser: 'none'
-          - runner: 'buildjet-4vcpu-ubuntu-2204-arm'
-            tag: 'noweb-arm'
-            platform: 'linux/arm64'
-            browser: 'none'
-
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v3
-      - name: Set up Docker Buildx
-        uses: docker/setup-buildx-action@v2
-
-      - name: Docker meta
-        id: meta
-        uses: docker/metadata-action@v4
-        with:
-          images: ${{ vars.DOCKER_IMAGE }}
-          flavor: latest=false
-          tags: |
-            type=raw,value=${{ inputs.tag }}-${{ matrix.tag }}
-
-      - name: Login to image repository
-        if: github.ref_type == 'tag'
-        uses: docker/login-action@v2
-        with:
-          username: ${{ secrets.DOCKER_USER }}
-          password: ${{ secrets.DOCKER_TOKEN }}
-
-      - name: Build and push
-        uses: docker/build-push-action@v4
-        with:
-          context: .
-          file: Dockerfile
-          platforms: ${{ matrix.platform }}
-          build-args: |
-            USE_BROWSER=${{ matrix.browser }}
-          push: ${{ inputs.push }}
-          tags: ${{ steps.meta.outputs.tags }}
-          labels: ${{ steps.meta.outputs.labels }}

.gitignore

@@ -1,14 +1,27 @@
+openapi.json
+tmp/*
+src/core/engines/gows/proto
+.env
+.envs/*
+*.heapsnapshot
 .yarn
 example.ts
 .*sessions
+sessions
 .secrets
+.minio
+.media
 tokens
 files
 venv
 .wwebjs_auth
+src/test.ts
+src/test.js
 test.js
 .wwebjs_cache
 src/dashboard
+.eslintcache
+__pycache__
 
 # compiled output
 /dist

.nvmrc

@@ -1 +1 @@
-v20.5.0
+v24.11

.oxlintrc.json

@@ -0,0 +1,15 @@
+{
+  "$schema": "./node_modules/oxlint/configuration_schema.json",
+  "plugins": ["typescript"],
+  "env": {
+    "builtin": true
+  },
+  "rules": {
+    "@typescript-eslint/explicit-function-return-type": "off",
+    "@typescript-eslint/explicit-module-boundary-types": "off",
+    "@typescript-eslint/no-inferrable-types": "off",
+    "@typescript-eslint/no-explicit-any": "off",
+    "@typescript-eslint/ban-ts-comment": "off",
+    "no-unused-vars": "off"
+  }
+}

.pre-commit-config.yaml

@@ -2,40 +2,50 @@ exclude: |
   (?x)^(
     ^src/dashboard/.*|
     ^src/core/engines/webjs/.*html|
-    ^src/plus/engines/webjs/.*html
+    ^src/core/engines/gows/grpc/.*|
+    ^src/core/engines/gows/proto/.*|
+    ^src/plus/engines/webjs/.*html|
+    ^.yarn/.*
   )$
 
 repos:
   - repo: local
     hooks:
-      - id: lint
-        name: lint
+      - id: commit-message-prefix
+        name: Validate Commit Message for src/plus Changes
+        entry: python ./.precommit/validate_commit_message.py
+        language: python
+        stages: [commit-msg]
+
+      - id: oxlint
+        name: oxlint
+        entry: npx oxlint --fix --deny-warnings
         language: system
-        entry: bash -c '$HOME/.nvm/nvm-exec npm run lint'
-        pass_filenames: false
-        files: |
-          (?x)^(
-              src/.*|
-          )$
+        pass_filenames: true
+        files: \.(ts|tsx|js|jsx)$
 
   - repo: https://github.com/pre-commit/mirrors-prettier
     rev: 'v3.1.0'
     hooks:
       - id: prettier
+        stages: [pre-commit]
         exclude: |
           (?x)^(
               docs/.*|
               README.md|
+              tests/smoke/goss.yaml|
           )$
   - repo: https://github.com/Lucas-C/pre-commit-hooks-nodejs
     rev: v1.1.2
     hooks:
       - id: markdown-toc
+        stages: [pre-commit]
         name: README.md
         files: ^README.md$
   - repo: local
     hooks:
       - id: no-plus-in-core
+        stages: [pre-commit]
         name: No "plus" in core
         language: pygrep
         entry: 'plus'
@@ -50,11 +60,18 @@ repos:
   - repo: local
     hooks:
       - id: no-console-log
+        stages: [pre-commit]
         name: No console.log() calls
         language: pygrep
         entry: 'console\.log'
         exclude: |
           (?x)^(
+              entrypoint.sh|
+              AGENTS.md|
               .pre-commit-config.yaml|
               ^src/core/engines/webjs/session.webjs.core.ts|
+              ^src/core/engines/webjs/_lodash.js|
+              ^tests/perf/.*|
+              ^scripts/.*|
+              ^scripts/init-waha.js|
           )$

.precommit/validate_commit_message.py

@@ -0,0 +1,38 @@
+import subprocess
+import sys
+
+
+def get_staged_files():
+    result = subprocess.run(["git", "diff", "--cached", "--name-only"], stdout=subprocess.PIPE, text=True)
+    files = result.stdout.splitlines()
+    return files
+
+
+def get_commit_message(commit_msg_filepath):
+    with open(commit_msg_filepath, 'r') as f:
+        return f.readline().strip()
+
+
+def main():
+    commit_msg_filepath = sys.argv[1]
+    commit_message = get_commit_message(commit_msg_filepath)
+    staged_files = get_staged_files()
+
+    has_plus_changes = any(f.startswith('src/plus') for f in staged_files)
+    print(commit_message)
+    starts_with_plus = commit_message.startswith('[PLUS]')
+
+    if has_plus_changes and not starts_with_plus:
+        print("'[PLUS]' not found in commit message, but there's changes are from 'src/plus'.")
+        return 1
+
+    if starts_with_plus and not all(f.startswith('src/plus') for f in staged_files):
+        print("'[PLUS]' found in commit message, but there's changes from other directories. \n"
+              "Changes MUST be only from 'src/plus'.")
+        return 1
+
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

.yarnrc.yml

@@ -1,3 +1,32 @@
+approvedGitRepositories:
+  - '**'
+
+compressionLevel: mixed
+
+enableGlobalCache: false
+
+enableScripts: true
+
 nodeLinker: node-modules
 
-yarnPath: .yarn/releases/yarn-3.6.3.cjs
+npmMinimalAgeGate: 0
+
+supportedArchitectures:
+  cpu:
+    - arm
+    - arm64
+    - ia32
+    - loong64
+    - mips
+    - mipsel
+    - ppc64
+    - riscv64
+    - s390
+    - s390x
+    - x64
+    - wasm32
+  os:
+    - current
+    - darwin
+    - linux
+    - win32

AGENTS.md

@@ -0,0 +1,131 @@
+# WAHA Agent Playbook
+
+This guide summarizes how to explore, modify, and validate the WhatsApp HTTP API
+(WAHA) codebase when assisting as an automation or coding agent.
+
+## Product & Variants
+
+- WAHA ships in **Core** and **Plus** editions
+- Core lives under `src/core` and supports the default session with minimal
+  media features
+- Plus extends core via `src/plus` to add multi-session orchestration, richer
+  media handling, and external storage integrations
+- Core code must remain free from Plus-only references (pre-commit hook rejects
+  "plus" in core files)
+- Commit subjects: changes that touch `src/plus` require `[PLUS] …` prefix;
+  everything else uses `[core] …`
+
+## Tech Stack
+
+- **Runtime**: Node.js 22.x, Yarn 3.6 (Berry)
+- **Framework**: NestJS v11 with dependency injection and modular controllers in
+  `src/api`
+- **Engines**: WhatsApp engines are abstracted (`WEBJS`, `GOWS`, `NOWEB`,
+  `WPP`). Core uses `SessionManagerCore`; Plus swaps to `SessionManagerPlus`
+  with extra storage backends (Mongo/Postgres/SQLite)
+- **ESM Bridge**: ESM-only dependencies (Baileys) load through
+  `src/vendor/esm.ts`
+- **Utilities**: RxJS streams drive webhook event fan-out. Prefer existing
+  helpers in `src/utils` and `src/core/utils`
+
+## Key Paths
+
+- `src/main.ts`: runtime entry point; dynamically loads AppModule (Core vs Plus)
+- `src/api/**`: REST controllers and WebSocket gateway
+- `src/core/**`: shared abstractions (config services, engine bootstrap,
+  storage, session management)
+- `src/plus/**`: multi-session orchestration, advanced media services, and
+  external persistence layers
+- `src/structures/**` and `src/utils/**`: DTOs, enums (event names follow
+  `domain.action`), helper utilities
+
+## Coding Expectations
+
+- Favor composability and long-lived solutions
+- Reuse existing helpers (`parseBool`, `DefaultMap`, media factories) instead of
+  reinventing logic
+- Stick to NestJS patterns: inject dependencies through constructors, expose
+  provider tokens from modules
+- Logging goes through injected `PinoLogger` or helpers in
+  `src/utils/logging.ts`
+- Respect path aliases (`@waha/...`) defined in `tsconfig.json`
+- Prefer named function declarations over `const` arrow functions
+- Avoid naming unused variables with a leading underscore
+- Always use explicit property names in object literals — never shorthand: write
+  `{ key: value }`, not `{ value }` (even when the variable name matches the
+  key)
+- Do not write verbose ternaries; use idiomatic helpers like `??` (nullish
+  coalescing)
+- Do not place `await` or other async calls inside ternary expressions (`?:`) or
+  nullish-coalescing expressions (`??`); use explicit `if/else` blocks or assign
+  the awaited value to a variable first
+- For configs, prefer runtime configurability over constants (environment keys
+  follow `WAHA_*` and `WAHA_SESSION_CONFIG_*`)
+- Do not use decorative comment blocks (lines of dashes/underscores with a
+  label) such as `// ─────────── NAME ───────────`; use plain inline comments or
+  no comment at all
+
+## How to Run API
+
+```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
+```
+
+## Code Guidelines
+
+- 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`
+
+## MCP Tools
+
+MCP tools live in `src/apps/mcp/tools/` and expose the HTTP API to AI clients.
+Each tool file mirrors an API domain (e.g. `chats.tools.ts` → chats endpoints).
+
+**When you change an existing API endpoint:**
+
+- Check the corresponding `*.tools.ts` file and update the tool's `inputSchema`,
+  description, or behavior if the API signature changed.
+
+**When you add a new API endpoint:**
+
+- Ask the user whether an MCP tool is needed for the new endpoint before
+  creating one.
+- If yes, add the tool to the matching `*.tools.ts` file (or create a new file
+  for a new domain).
+- Every `@Tool` decorator must include an `annotations` block with all three
+  fields:
+  ```typescript
+  annotations: {
+    readOnlyHint: true | false,   // true = no side effects (GET-style)
+    destructiveHint: true | false, // true = irreversible deletion/logout
+    idempotentHint: true | false,  // true = safe to repeat with same args
+  }
+  ```
+- Input schemas live in the matching `*.zod.ts` file.
+- Tools call the API via `this.textRequest({ method, url, ... })` inherited from
+  `McpController`.
+
+## Related Sources
+
+- WEBJS: `../whatsapp-web.js`
+- NOWEB: `../WhiskeySockets-Baileys` and `../whatsapp-rust-bridge`
+- GOWS: `../gows` and `../whatsmeow`
+- WPP: `../wa-js`, `../wppconnect`, `../wppconnect-server`
+- ChatWoot: `../chatwoot`

CLAUDE.md

@@ -0,0 +1 @@
+AGENTS.md

Dockerfile

@@ -1,61 +1,172 @@
+ARG NODE_IMAGE_TAG=24.11-bookworm-slim
+ARG GOLANG_IMAGE_TAG=1.24-bookworm
+
 #
 # Build
 #
-ARG NODE_VERSION=20.12.2-bullseye
-FROM node:${NODE_VERSION} as build
+FROM node:${NODE_IMAGE_TAG} AS build
 ENV PUPPETEER_SKIP_DOWNLOAD=True
 
+# git + build toolchain for git deps
+RUN apt-get update && \
+    apt-get install -y --no-install-recommends git python3 build-essential curl ca-certificates unzip && \
+    rm -rf /var/lib/apt/lists/*
+
 # npm packages
-WORKDIR /src
+WORKDIR /git
 COPY package.json .
 COPY yarn.lock .
-RUN yarn set version 3.6.3
+COPY .yarnrc.yml .
+ENV YARN_CHECKSUM_BEHAVIOR=update
+
+RUN npm install -g corepack && corepack enable
 RUN yarn install
 
 # App
-WORKDIR /src
-ADD . /src
+WORKDIR /git
+ADD . /git
 RUN yarn install
 RUN yarn build && find ./dist -name "*.d.ts" -delete
 
+# Rebuild sharp from source on x86-64 so it runs on pre-v2 CPUs (no SSE4.2 requirement).
+# The prebuilt @img/sharp-linux-x64 binary requires x86-64-v2; -march=x86-64 limits
+# code generation to baseline x86-64 (SSE2 only). ARM64 prebuilts have no such
+# constraint, so no rebuild is needed there.
+# We call sharp's own install/build.js (not npm rebuild) so it first generates config.gypi
+# with include/lib paths pointing to its bundled @img/sharp-libvips-linux-x64 package,
+# then invokes node-gyp with those paths. Without this step node-gyp cannot find vips headers.
+RUN if [ "$(uname -m)" = "x86_64" ]; then \
+        LIBVIPS_DEV_VER=$(node -e "require('/git/node_modules/sharp/package.json').devDependencies['@img/sharp-libvips-dev']" | tr -d '^') && \
+        npm install --prefix /tmp/sharp-dev --no-package-lock "@img/sharp-libvips-dev@${LIBVIPS_DEV_VER}" && \
+        cp -r /tmp/sharp-dev/node_modules/@img/sharp-libvips-dev /git/node_modules/@img/ && \
+        cd /git/node_modules/sharp && \
+        PATH="/git/node_modules/.bin:$PATH" CFLAGS="-march=x86-64" CXXFLAGS="-march=x86-64" node install/build.js; \
+    fi
+
 #
 # Dashboard
 #
-FROM node:${NODE_VERSION} as dashboard
+FROM node:${NODE_IMAGE_TAG} AS dashboard
 
-# Download WAHA Dashboard
-ENV WAHA_DASHBOARD_SHA 63fd6e9e23e90f90e8aa0de04feb3f1909f63021
+# jq to parse json
+RUN apt-get update && apt-get install -y jq && rm -rf /var/lib/apt/lists/*
+
+# wget, unzip
+RUN apt-get update && apt-get install -y wget unzip && rm -rf /var/lib/apt/lists/*
+
+COPY waha.config.json /tmp/waha.config.json
 RUN \
-    wget https://github.com/devlikeapro/dashboard/archive/${WAHA_DASHBOARD_SHA}.zip \
+    WAHA_DASHBOARD_GITHUB_REPO=$(jq -r '.waha.dashboard.repo' /tmp/waha.config.json) && \
+    WAHA_DASHBOARD_SHA=$(jq -r '.waha.dashboard.ref' /tmp/waha.config.json) && \
+    wget https://github.com/${WAHA_DASHBOARD_GITHUB_REPO}/archive/${WAHA_DASHBOARD_SHA}.zip \
     && unzip ${WAHA_DASHBOARD_SHA}.zip -d /tmp/dashboard \
     && mkdir -p /dashboard \
     && mv /tmp/dashboard/dashboard-${WAHA_DASHBOARD_SHA}/* /dashboard/ \
     && rm -rf ${WAHA_DASHBOARD_SHA}.zip \
     && rm -rf /tmp/dashboard/dashboard-${WAHA_DASHBOARD_SHA}
 
+#
+# GOWS
+#
+FROM golang:${GOLANG_IMAGE_TAG} AS gows
+
+# jq to parse json
+RUN apt-get update && apt-get install -y jq && rm -rf /var/lib/apt/lists/*
+
+# install protoc
+RUN apt-get update && \
+    apt-get install protobuf-compiler -y
+
+# Image processing for thumbnails
+RUN apt-get update  \
+    && apt-get install -y libvips-dev \
+    && rm -rf /var/lib/apt/lists/*
+
+COPY waha.config.json /tmp/waha.config.json
+WORKDIR /go/gows
+RUN \
+    GOWS_GITHUB_REPO=$(jq -r '.waha.gows.repo' /tmp/waha.config.json) && \
+    GOWS_SHA=$(jq -r '.waha.gows.ref' /tmp/waha.config.json) && \
+    ARCH=$(uname -m) && \
+    if [ "$ARCH" = "x86_64" ]; then ARCH="amd64"; \
+    elif [ "$ARCH" = "aarch64" ]; then ARCH="arm64"; \
+    else echo "Unsupported architecture: $ARCH" && exit 1; fi && \
+    mkdir -p /go/gows/bin && \
+    wget -O /go/gows/bin/gows https://github.com/${GOWS_GITHUB_REPO}/releases/download/${GOWS_SHA}/gows-${ARCH} && \
+    chmod +x /go/gows/bin/gows
+
+
 #
 # Final
 #
-FROM node:${NODE_VERSION} as release
+FROM node:${NODE_IMAGE_TAG} AS release
 ENV PUPPETEER_SKIP_DOWNLOAD=True
 # Quick fix for memory potential memory leaks
 # https://github.com/devlikeapro/waha/issues/347
 ENV NODE_OPTIONS="--max-old-space-size=16384"
 ARG USE_BROWSER=chromium
+ARG WHATSAPP_DEFAULT_ENGINE
 
 RUN echo "USE_BROWSER=$USE_BROWSER"
 
 # Install ffmpeg to generate previews for videos
 RUN apt-get update && apt-get install -y ffmpeg --no-install-recommends && rm -rf /var/lib/apt/lists/*
 
+# Image processing for thumbnails
+RUN apt-get update  \
+    && apt-get install -y libvips \
+    && rm -rf /var/lib/apt/lists/*
+
+# Install zip and unzip - either for chromium or chrome
+RUN if [ "$USE_BROWSER" = "chromium" ] || [ "$USE_BROWSER" = "chrome" ]; then \
+    apt-get update  \
+    && apt-get install -y zip unzip \
+    && rm -rf /var/lib/apt/lists/*; \
+    fi
+
+# Install wget - either for chromium or chrome
+RUN if [ "$USE_BROWSER" = "chromium" ] || [ "$USE_BROWSER" = "chrome" ]; then \
+    apt-get update  \
+    && apt-get install -y wget \
+    && rm -rf /var/lib/apt/lists/*; \
+    fi
+
 # Install fonts if using either chromium or chrome
 RUN if [ "$USE_BROWSER" = "chromium" ] || [ "$USE_BROWSER" = "chrome" ]; then \
     apt-get update  \
-    && apt-get install -y fonts-ipafont-gothic fonts-wqy-zenhei fonts-thai-tlwg fonts-kacst fonts-freefont-ttf \
+    && apt-get install -y \
+        fontconfig \
+        fonts-freefont-ttf \
+        fonts-gfs-neohellenic \
+        fonts-indic \
+        fonts-ipafont-gothic \
+        fonts-kacst \
+        fonts-liberation \
+        fonts-noto-cjk \
+        fonts-noto-color-emoji \
+        fonts-roboto \
+        fonts-thai-tlwg \
+        fonts-wqy-zenhei \
+        fonts-open-sans \
       --no-install-recommends \
     && rm -rf /var/lib/apt/lists/*; \
     fi
 
+# Install xvfb, xauth
+RUN if [ "$USE_BROWSER" = "chromium" ] || [ "$USE_BROWSER" = "chrome" ]; then \
+    apt-get update && apt-get install -y --no-install-recommends \
+        xvfb \
+        xauth \
+        libnss3 \
+        libxss1 \
+        libasound2 \
+        libatk-bridge2.0-0 \
+        libgtk-3-0 \
+        libdrm2 \
+        ca-certificates \
+        && rm -rf /var/lib/apt/lists/*; \
+    fi
+
 # Install Chromium
 RUN if [ "$USE_BROWSER" = "chromium" ]; then \
         apt-get update  \
@@ -68,7 +179,8 @@ RUN if [ "$USE_BROWSER" = "chromium" ]; then \
 # Install Chrome
 # Available versions:
 # https://www.ubuntuupdates.org/package/google_chrome/stable/main/base/google-chrome-stable
-ARG CHROME_VERSION="126.0.6478.182-1"
+ARG CHROME_VERSION="152.0.7977.82-1"
+ARG OPUSTAGS_VERSION="1.10.1"
 RUN if [ "$USE_BROWSER" = "chrome" ]; then \
         wget --no-verbose -O /tmp/chrome.deb https://dl.google.com/linux/chrome/deb/pool/main/g/google-chrome-stable/google-chrome-stable_${CHROME_VERSION}_amd64.deb \
           && apt-get update \
@@ -77,17 +189,68 @@ RUN if [ "$USE_BROWSER" = "chrome" ]; then \
           && rm -rf /var/lib/apt/lists/*; \
     fi
 
+# curl
+RUN apt-get update  \
+    && apt-get install -y curl \
+    && rm -rf /var/lib/apt/lists/*
+
+# Build and install opustags so audio metadata can be cleaned up inside the container
+RUN set -eux; \
+    buildDeps='build-essential cmake pkg-config libogg-dev'; \
+    apt-get update; \
+    apt-get install -y --no-install-recommends ${buildDeps}; \
+    mkdir -p /tmp/opustags; \
+    curl -L https://github.com/fmang/opustags/archive/refs/tags/${OPUSTAGS_VERSION}.tar.gz \
+      | tar -xz -C /tmp/opustags; \
+    cd /tmp/opustags/opustags-${OPUSTAGS_VERSION}; \
+    cmake -S . -B build -DCMAKE_INSTALL_PREFIX=/usr/local -DCMAKE_BUILD_TYPE=Release; \
+    cmake --build build --config Release; \
+    cmake --install build; \
+    rm -rf /tmp/opustags; \
+    apt-get purge -y --auto-remove ${buildDeps}; \
+    rm -rf /var/lib/apt/lists/*
+
+# GOWS requirements
+# libc6
+RUN  apt-get update \
+     && apt-get install -y libc6 \
+     && rm -rf /var/lib/apt/lists/*
+
+# Install tini for proper init process
+RUN apt-get update && apt-get install -y tini && rm -rf /var/lib/apt/lists/*
+
+# Set the ENV for docker image
+ENV WHATSAPP_DEFAULT_ENGINE=$WHATSAPP_DEFAULT_ENGINE
+
 # Attach sources, install packages
 WORKDIR /app
 COPY package.json ./
-COPY --from=build /src/node_modules ./node_modules
-COPY --from=build /src/dist ./dist
+COPY --from=build /git/node_modules ./node_modules
+COPY --from=build /git/dist ./dist
 COPY --from=dashboard /dashboard ./dist/dashboard
+COPY --from=gows /go/gows/bin/gows /app/gows
+COPY .env.example ./.env.example
+COPY scripts/init-waha.js ./scripts/init-waha.js
+RUN chmod +x ./scripts/init-waha.js \
+  && printf '%s\n' '#!/bin/sh' 'exec node /app/scripts/init-waha.js "$@"' > /usr/local/bin/init-waha \
+  && chmod +x /usr/local/bin/init-waha
+ENV WAHA_GOWS_PATH=/app/gows
+ENV WAHA_GOWS_SOCKET=/tmp/gows.sock
+
+COPY entrypoint.sh /entrypoint.sh
 
 # Chokidar options to monitor file changes
 ENV CHOKIDAR_USEPOLLING=1
 ENV CHOKIDAR_INTERVAL=5000
 
+# WAHA variables
+ENV WAHA_ZIPPER=ZIPUNZIP
+
+# GOWS - use libc DNS resolver
+ENV GODEBUG=netdns=cgo
+
 # Run command, etc
 EXPOSE 3000
-CMD yarn start:prod
+# Use tini as init system to handle zombie processes properly
+ENTRYPOINT ["/usr/bin/tini", "--"]
+CMD ["/entrypoint.sh"]

Makefile

@@ -1,16 +1,19 @@
+build-all: build-plus build-chrome build-gows build-noweb
+
 build:
 	docker build . -t devlikeapro/waha
 
+build-plus:
+	docker build . -t devlikeapro/waha-plus
+
 build-chrome:
 	docker build . -t devlikeapro/waha-plus:chrome --build-arg USE_BROWSER=chrome
 
 build-noweb:
-	docker build . -t devlikeapro/waha:noweb --build-arg USE_BROWSER=none
+	docker build . -t devlikeapro/waha-plus:noweb --build-arg USE_BROWSER=none --build-arg WHATSAPP_DEFAULT_ENGINE=NOWEB
 
-build-all: build build-chrome build-noweb
-
-build-plus:
-	docker build . -t devlikeapro/waha-plus
+build-gows:
+	docker build . -t devlikeapro/waha-plus:gows --build-arg USE_BROWSER=none --build-arg WHATSAPP_DEFAULT_ENGINE=GOWS
 
 build-ssh:
 	# check IMAGE provided
@@ -29,13 +32,62 @@ push:
 	docker push devlikeapro/waha
 
 for-swagger:
-	WHATSAPP_SWAGGER_CONFIG_ADVANCED=true . ${NVM_DIR}/nvm.sh && nvm exec yarn start
+	export WHATSAPP_SWAGGER_CONFIG_ADVANCED=true && export WHATSAPP_SWAGGER_PASSWORD=666 && yarn start
 
 up-noweb:
-	. ${NVM_DIR}/nvm.sh && nvm exec yarn up @adiwajshing/baileys@github:devlikeapro/Baileys#fork-master-channels
+	yarn up @adiwajshing/baileys@github:devlikeapro/Baileys#fork-master-2026-04-28
+
+up-noweb-libsignal:
+	yarn up libsignal@github:devlikeapro/libsignal-node#fork-master
 
 up-webjs:
-	. ${NVM_DIR}/nvm.sh && nvm exec yarn up whatsapp-web.js@github:devlikeapro/whatsapp-web.js#fork-webpack-exodus-channels
+	yarn up whatsapp-web.js@github:devlikeapro/whatsapp-web.js#fork-main-2026-06-26
+
+link-webjs:
+	yarn up whatsapp-web.js@link:../whatsapp-web.js
+
+unlink-webjs: up-webjs
+
+rebuild-noweb:
+	cd ../Baileys && yarn build
+
+link-noweb: rebuild-noweb
+	yarn up @adiwajshing/baileys@link:../Baileys
+
+unlink-noweb: up-noweb
+
+up-wpp:
+	SHARP_IGNORE_GLOBAL_LIBVIPS=1 yarn up @wppconnect-team/wppconnect@github:wppconnect-team/wppconnect#master
+	SHARP_IGNORE_GLOBAL_LIBVIPS=1 yarn up @wppconnect/wa-js@github:wppconnect-team/wa-js#main
+
+up-rust-bridge:
+	yarn up -R whatsapp-rust-bridge
 
 start-proxy:
 	docker run --rm -d --name squid-container -e TZ=UTC -p 3128:3128 ubuntu/squid:5.2-22.04_beta
+
+proto-gows:
+	node scripts/gows-proto.js build --dir ../gows/proto
+
+gows:
+	cd ../gows && \
+	(export PATH=${HOME}/go/bin:${PATH} || echo failed) && \
+	make all
+
+ORIGIN ?= waha-plus
+CORE_REMOTE ?= waha
+
+release:
+	node scripts/release.js
+
+release-push: release
+	git push $(ORIGIN) core plus
+	git push --force-with-lease $(ORIGIN) dev
+	git push $(CORE_REMOTE) core
+
+up-dashboard:
+	node scripts/up-dashboard.js
+
+copy-dashboard:
+	cd ../waha-hub/ui && \
+	make copy-waha

README.md

@@ -6,22 +6,16 @@
 
 **WAHA** - **W**hats**A**pp **H**TTP **A**PI (REST API) that you can install on your own server and run in less than 5 minutes!
 
-[![Docker Pulls](https://img.shields.io/docker/pulls/devlikeapro/whatsapp-http-api)](https://hub.docker.com/r/devlikeapro/waha)
+[![Docker Pulls](https://img.shields.io/docker/pulls/devlikeapro/waha)](https://hub.docker.com/r/devlikeapro/waha)
 
 - Documentation: [https://waha.devlike.pro/](https://waha.devlike.pro/)
+- Dashboard Example: [https://waha.devlike.pro/dashboard](https://waha.devlike.pro/dashboard)
 - Swagger Example: [https://waha.devlike.pro/swagger](https://waha.devlike.pro/swagger)
 
 # Tables of Contents
 
 <!-- toc -->
 
-- [Features](#features)
-  * [Messages](#messages)
-  * [Sessions](#sessions)
-  * [Security](#security)
-  * [Updates](#updates)
-  * [Groups](#groups)
-  * [Contacts](#contacts)
 - [Quick start](#quick-start)
   * [Requirements](#requirements)
   * [Send your first message](#send-your-first-message)
@@ -32,52 +26,11 @@
     + [5. Get the screenshot](#5-get-the-screenshot)
     + [6. Send a text message](#6-send-a-text-message)
   * [What is next?](#what-is-next)
+- [Development](#development)
+  * [Start the project](#start-the-project)
 
 <!-- tocstop -->
 
-# Features
-
-## Messages
-- Send messages  
-- Receive messages  
-- Message replies  
-- Send location  
-- Receive location  
-- React to messages  
-- Send media (images/documents/files) 
-- Send voice messages 
-- Receive media (images/audio/video/documents) 
-- Receive messages - webhook retries 
-
-## Sessions
-- Multi Device  
-- Get the screenshot  
-- Session saving (don't have to scan QR on every restart) 
-- Single WhatsApp account running inside one container 
-- Multiple WhatsApp account running inside one container 
-
-## Security
-- Swagger panel authentication 
-- API authentication 
-
-## Updates
-- Bug fixes and updates come as soon as they are implemented. 
-
-## Groups
-- Create a group
-- Get invite for group
-- Modify group info (subject, description)
-- Add group participants
-- Kick group participants
-- Promote/demote group participants
-
-## Contacts
-- Mute/unmute chats
-- Block/unblock contacts
-- Get contact info
-- Get profile pictures
-- Get presence (online\offline\typing) status
-
 # Quick start
 
 ## Requirements
@@ -87,13 +40,6 @@ instruction <a href="https://docs.docker.com/get-docker/" target="_blank" rel="n
 
 When you are ready - come back and follows the below steps to send the first text message to WhatsApp via HTTP API!
 
-{{< details "Why Docker?" >}}
-Docker makes it easy to ship all-in-one solution with the runtime and dependencies. You don't have to worry about
-language-specific libraries or chrome installation.
-
-Also Docker makes installation and update processes so simple, just one command!
-{{< /details >}}
-
 ## Send your first message
 
 Let's go over steps that allow you to send your first text message via WhatsApp HTTP API!
@@ -114,7 +60,7 @@ docker pull devlikeapro/waha-plus
 docker logout
 ```
 
-Read more about how to get `PASSWORD` for [Plus Version →]({{< relref "plus-version" >}})
+Read more about how to get `PASSWORD` for [**➕ WAHA Plus**](https://waha.devlike.pro/docs/how-to/waha-plus/)
 
 ### 2. Run WhatsApp HTTP API
 
@@ -141,7 +87,7 @@ later:
 How to log in - the instruction on WhatsApp site
 </a>
 
-When your ready - find `POST /api/session/start`, click on **Try it out**, then **Execute** a bit below.
+When your ready - find `POST /api/sessions`, click on **Try it out**, then **Execute** a bit below.
 
 
 The example payload:
@@ -195,3 +141,30 @@ curl -d "{\"chatId\": \"${PHONE}@c.us\", \"text\": \"Hello from WhatsApp HTTP AP
 
 ## What is next?
 [Go and read the full documentation!](https://waha.devlike.pro/docs/overview/introduction/)
+
+# Development
+
+## Start the project
+1. Clone the repository
+2. Make sure you're using node>=22 (check [.nvmrc](/.nvmrc) to get the version)
+3. Install the **whatsapp-rust-bridge prerequisites**:
+ ```bash
+# Bun runtime used by whatsapp-rust-bridge prepare scripts
+curl -fsSL https://bun.sh/install | bash -s -- bun-v1.3.9
+
+# Rust nightly toolchain used for whatsapp-rust-bridge
+curl -fsSL https://sh.rustup.rs | bash -s -- -y --default-toolchain nightly-2026-01-30
+rustup target add wasm32-unknown-unknown
+cargo install wasm-pack --vers 0.14.0 --locked
+```
+
+4. Run the following commands:
+```bash
+# Install dependencies
+yarn install
+# Fetch and compile proto files
+yarn gows:proto
+# Run
+yarn start
+# open http://localhost:3000
+```

docker-compose.yaml

@@ -1,203 +1,104 @@
-#
 # https://waha.devlike.pro/docs/how-to/install/
-# Here's we provide a simple example of how to install WAHA using Docker Compose.
-#
-# We're assuming you have Docker and Docker Compose installed.
-# If you don't have Docker Compose installed, you can follow the official guide:
-# https://docs.docker.com/compose/install/
-#
-
 services:
   waha:
-    # Always restart the container on failure
     restart: always
-
-    #
-    # Image
-    #
-    image: devlikeapro/waha-plus:latest # or devlikeapro/waha:latest if you're using WAHA Core
-    #
-    # We strongly recommend using the pinned version of WAHA
-    # https://waha.devlike.pro/docs/how-to/engines/#versions
-    # image: devlikeapro/waha-plus:latest-2024.7.6 # 'latest' is not mistaken here
-    #
-    # Multiple images are available
     # https://waha.devlike.pro/docs/how-to/engines/#docker-images
-    # image: devlikeapro/waha-plus:chrome
-    #
+    # https://portal.devlike.pro/docker-image
+    image: devlikeapro/waha-plus
+    # WAHA Core
+    # image: devlikeapro/waha:latest
+
+    # Add "dns" if you have a problem with resolving "web.whatsapp.com"
+    dns:
+      - 1.1.1.1
+      - 8.8.8.8
+
+    logging:
+      driver: 'json-file'
+      options:
+        max-size: '100m'
+        max-file: '10'
 
-    # The first port can be any free port you want
-    # The second port must be the same as WHATSAPP_API_PORT or 3000 by default
-    # Consider using the same port for simplicity
     ports:
-      - '3000:3000/tcp'
-      # NOTE: if you're using HTTP, you can use the following port mapping
-      #- '80:3000/tcp'
-      # NOTE: if you're using HTTPS, you can use the following port mapping
-      #- '443:3000/tcp'
+      - '127.0.0.1:3000:3000/tcp'
 
     volumes:
       # Store sessions in the .sessions folder (comment it if you're using MongoDB)
-      # Doesn't work with WAHA Core
-      - './.sessions:/app/.sessions'
+      - './sessions:/app/.sessions'
 
+      # Save media files
       # https://waha.devlike.pro/docs/how-to/storages/#save-media-files-between-the-container-restarts
-      - './.media:/app/.media'
+      - './media:/app/.media'
 
-      # If you're using certbot for HTTPS, you can use the following volume mapping
-      # https://waha.devlike.pro/blog/setting-up-https-for-waha/#lets-encrypt-certbot--waha
-      # - '/etc/letsencrypt:/etc/letsencrypt'
+    env_file:
+      - .env
 
-    # WAHA Configuration
-    # https://waha.devlike.pro/docs/how-to/config/
-    environment:
-      #
-      # Common
-      #
-      # If you know the right URL, you can use it here.
-      # Use any port in WHATSAPP_API_PORT and domain in WHATSAPP_API_HOSTNAME
-      # https://waha.devlike.pro/docs/how-to/config/#common
-      #- WHATSAPP_API_PORT=3000
-      #- WHATSAPP_API_HOSTNAME=localhost
+# NOTE: Only if you're using PostgreSQL to save sessions
+# https://waha.devlike.pro/docs/how-to/storages/#media---postgresql
+#  postgres:
+#    image: postgres:17.6
+#    restart: always
+#    environment:
+#      POSTGRES_USER: postgres
+#      POSTGRES_PASSWORD: postgres
+#      POSTGRES_DB: postgres
+#    ports:
+#      - "127.0.0.1:5432:5432"
+#    volumes:
+#      - pg_data:/var/lib/postgresql/data
+#    command:
+#      - postgres
+#      - "-c"
+#      - "max_connections=3000"
+#    logging:
+#      driver: "json-file"
+#      options:
+#        max-size: "100m"
+#        max-file: "10"
 
-      #
-      # Security
-      #
-      # https://waha.devlike.pro/docs/how-to/security/
-      #
-      - WHATSAPP_API_KEY=321
-      - WAHA_DASHBOARD_USERNAME=waha
-      - WAHA_DASHBOARD_PASSWORD=waha
-      #- WHATSAPP_SWAGGER_USERNAME=admin
-      #- WHATSAPP_SWAGGER_PASSWORD=admin
-
-      #
-      # Dashboard
-      #
-      # https://waha.devlike.pro/docs/how-to/waha-dashboard/#configuration
-      # Enabled by default
-      #- WAHA_DASHBOARD_ENABLED=true
-      #- WAHA_DASHBOARD_USERNAME=waha
-      #- WAHA_DASHBOARD_PASSWORD=waha
-
-      #
-      # Logging
-      # https://waha.devlike.pro/docs/how-to/observability/#logging
-      #
-      - WAHA_LOG_FORMAT=PRETTY
-      # Set log format to JSON if you consume logs with log management systems
-      #- WAHA_LOG_FORMAT=JSON
-      - WAHA_LOG_LEVEL=info
-      # If you want to see more logs, you can set the log level to debug
-      #- WAHA_LOG_LEVEL=debug
-      # DEBUG=1 # shortcut for setting log level to debug
-
-      #
-      # Engine
-      #
-      # Choose the right engine for your needs (WEBJS by default)
-      # https://waha.devlike.pro/docs/how-to/engines/
-      - WHATSAPP_DEFAULT_ENGINE=WEBJS
-      # Use NOWEB engine for the fastest performance
-      #- WHATSAPP_DEFAULT_ENGINE=NOWEB
-
-      #
-      # Sessions
-      #
-      # https://waha.devlike.pro/docs/how-to/config/#sessions
-      # Restart all sessions when container starts
-      - WHATSAPP_RESTART_ALL_SESSIONS=True
-      # Do not print QR codes in logs
-      - WAHA_PRINT_QR=False
-      #
-      # OR you can specify sessions by name, if you have handful amount of sessions
-      #- WHATSAPP_START_SESSION=session1,session2
-      # Do not use both WHATSAPP_RESTART_ALL_SESSIONS and WHATSAPP_START_SESSION parameters
-      #
-
-      #
-      # Swagger
-      #
-      # https://waha.devlike.pro/docs/how-to/swagger/
-      #- WHATSAPP_SWAGGER_USERNAME=admin
-      #- WHATSAPP_SWAGGER_PASSWORD=admin
-      # Disable Swagger
-      #- WHATSAPP_SWAGGER_ENABLED=false
-      # Enable advanced Swagger configuration
-      #- WHATSAPP_SWAGGER_CONFIG_ADVANCED=true
-      #
-      # Swagger White Label customization
-      # https://waha.devlike.pro/docs/how-to/swagger/#white-label
-      #- WHATSAPP_SWAGGER_TITLE=WAHA API
-      #
-
-      #
-      # Global Proxy Settings
-      # https://waha.devlike.pro/docs/how-to/config/#global-proxy-configuration
-      # You can also set proxy settings for each session later when starting it
-      # https://waha.devlike.pro/docs/how-to/sessions/#configure-proxy
-      #- WHATSAPP_PROXY_SERVER=proxy.example.com:3128
-      #-WHATSAPP_PROXY_SERVER_USERNAME=user
-      #-WHATSAPP_PROXY_SERVER_PASSWORD=pass
-      #
-
-      #
-      # HTTPS Configuration
-      #
-      # https://waha.devlike.pro/docs/how-to/config/#https
-      # Consider using certbot for HTTPS
-      # https://waha.devlike.pro/blog/setting-up-https-for-waha/#lets-encrypt-certbot--waha
-      #- WHATSAPP_API_HOSTNAME=waha.example.pro
-      #- WAHA_HTTPS_ENABLED=true
-      #- WAHA_HTTPS_PATH_KEY=/etc/letsencrypt/live/waha.example.pro/privkey.pem
-      #- WAHA_HTTPS_PATH_CERT=/etc/letsencrypt/live/waha.example.pro/cert.pem \
-      #- WAHA_HTTPS_PATH_CA=/etc/letsencrypt/live/waha.example.pro/chain.pem
-      #
-
-      #
-      # Media Configuration
-      #
-      # https://waha.devlike.pro/docs/how-to/config/#files
-      #
-      # Disable media (images, videos, files) download for incoming messages
-      #- WHATSAPP_DOWNLOAD_MEDIA=false
-      #
-      # Download only specific media types
-      #- WHATSAPP_FILES_MIMETYPES=image/jpeg,image/png
-      #
-      # Set to 0 to keep media files forever
-      # https://waha.devlike.pro/docs/how-to/storages/#save-media-files-between-the-container-restarts
-      - WHATSAPP_FILES_LIFETIME=0
-      - WHATSAPP_FILES_FOLDER=/app/.media
-      #
-      # Keep media files for 180 seconds (3 minutes)
-      #- WHATSAPP_FILES_LIFETIME=180
-      #
-
-      #
-      # Global Webhooks
-      #
-      # https://waha.devlike.pro/docs/how-to/config/#webhooks
-      # https://waha.devlike.pro/docs/how-to/webhooks/
-      #- WHATSAPP_HOOK_URL=https://webhook.site/11111111-1111-1111-1111-11111111
-      #- WHATSAPP_HOOK_EVENTS=session.status,message,message.reaction
-      #
-
-      #
-      # MongoDB Configuration
-      # https://waha.devlike.pro/docs/how-to/storages/#sessions---mongodb
-      #- WHATSAPP_SESSIONS_MONGO_URL=mongodb://mongodb:27017
-      #
-# NOTE: Uncomment this block to run WAHA+ with MongoDB
+# NOTE: Only if you're using MongoDB
+# https://waha.devlike.pro/docs/how-to/storages/#sessions---mongodb
+# Uncomment this block if you're using MongoDB
 #  mongodb:
 #    image: mongo
 #    container_name: mongodb
 #    ports:
-#      - '27017:27017/tcp'
+#      - '127.0.0.1:27017:27017/tcp'
 #    volumes:
 #      - mongodb_data:/data/db
-#    restart: always
+#    environment:
+#      - MONGO_INITDB_ROOT_USERNAME=mongouser
+#      - MONGO_INITDB_ROOT_PASSWORD=mongopassword
+#    logging:
+#      driver: "json-file"
+#      options:
+#        max-size: "100m"
+#        max-file: "10"
 
-# NOTE: Uncomment this block to run WAHA+ with MongoDB
-#volumes:
-#  mongodb_data: {}
+# NOTE: Only if you're using S3 to save media files
+# https://waha.devlike.pro/docs/how-to/storages/#media---s3
+# Uncomment this block if you're using AWS S3
+#  minio:
+#    image: quay.io/minio/minio
+#    container_name: minio
+#    restart: always
+#    ports:
+#      - '127.0.0.1:9000:9000'
+#      - '127.0.0.1:9001:9001'
+#    environment:
+#      MINIO_REGION: 'eu-west-2'
+#      MINIO_ROOT_USER: 'minioadmin'
+#      MINIO_ROOT_PASSWORD: 'minioadmin'
+#    volumes:
+#      - minio_data:/data
+#    command: server /data --console-address ":9001"
+#    logging:
+#      driver: "json-file"
+#      options:
+#        max-size: "100m"
+#        max-file: "10"
+
+volumes:
+  mongodb_data: {}
+  minio_data: {}
+  pg_data: {}

docker-compose/chatwoot/.chatwoot.env

@@ -0,0 +1,265 @@
+# Learn about the various environment variables at
+# https://www.chatwoot.com/docs/self-hosted/configuration/environment-variables/#rails-production-variables
+
+# Increase rack default timeout (30s) to avoid timeout errors
+# Workaround for https://github.com/devlikeapro/waha/issues/1389
+RACK_TIMEOUT_SERVICE_TIMEOUT=60
+
+# Used to verify the integrity of signed cookies. so ensure a secure value is set
+# SECRET_KEY_BASE should be alphanumeric. Avoid special characters or symbols. 
+# Use `rake secret` to generate this variable
+SECRET_KEY_BASE=replace_with_lengthy_secure_hex
+
+# Replace with the URL you are planning to use for your app
+FRONTEND_URL=http://chatwoot:3009
+# To use a dedicated URL for help center pages
+# HELPCENTER_URL=http://0.0.0.0:3000
+
+# If the variable is set, all non-authenticated pages would fallback to the default locale.
+# Whenever a new account is created, the default language will be DEFAULT_LOCALE instead of en
+# DEFAULT_LOCALE=en
+
+# If you plan to use CDN for your assets, set Asset CDN Host
+ASSET_CDN_HOST=
+
+# Force all access to the app over SSL, default is set to false
+FORCE_SSL=false
+
+# This lets you control new sign ups on your chatwoot installation
+# true : default option, allows sign ups
+# false : disables all the end points related to sign ups
+# api_only: disables the UI for signup, but you can create sign ups via the account apis
+ENABLE_ACCOUNT_SIGNUP=false
+
+# Redis config
+# specify the configs via single URL or individual variables
+# ref: https://www.iana.org/assignments/uri-schemes/prov/redis
+# You can also use the following format for the URL: redis://:password@host:port/db_number
+REDIS_URL=redis://redis:6379
+# If you are using docker-compose, set this variable's value to be any string,
+# which will be the password for the redis service running inside the docker-compose
+# to make it secure
+REDIS_PASSWORD=redis
+# Redis Sentinel can be used by passing list of sentinel host and ports e,g. sentinel_host1:port1,sentinel_host2:port2
+REDIS_SENTINELS=
+# Redis sentinel master name is required when using sentinel, default value is "mymaster".
+# You can find list of master using "SENTINEL masters" command
+REDIS_SENTINEL_MASTER_NAME=
+
+# By default Chatwoot will pass REDIS_PASSWORD as the password value for sentinels
+# Use the following environment variable to customize passwords for sentinels.
+# Use empty string if sentinels are configured with out passwords
+# REDIS_SENTINEL_PASSWORD=
+
+# Redis premium breakage in heroku fix
+# enable the following configuration
+# ref: https://github.com/chatwoot/chatwoot/issues/2420
+# REDIS_OPENSSL_VERIFY_MODE=none
+
+# Postgres Database config variables
+# You can leave POSTGRES_DATABASE blank. The default name of
+# the database in the production environment is chatwoot_production
+POSTGRES_DATABASE=chatwoot
+POSTGRES_HOST=postgres
+POSTGRES_USERNAME=postgres
+POSTGRES_PASSWORD=postgres
+RAILS_ENV=development
+# Changes the Postgres query timeout limit. The default is 14 seconds. Modify only when required.
+# POSTGRES_STATEMENT_TIMEOUT=14s
+RAILS_MAX_THREADS=5
+
+# The email from which all outgoing emails are sent
+# could user either  `email@yourdomain.com` or `BrandName <email@yourdomain.com>`
+MAILER_SENDER_EMAIL=Chatwoot <accounts@chatwoot.com>
+
+#SMTP domain key is set up for HELO checking
+SMTP_DOMAIN=chatwoot.com
+# Set the value to "mailhog" if using docker-compose for development environments,
+# Set the value as "localhost" or your SMTP address in other environments
+# If SMTP_ADDRESS is empty, Chatwoot would try to use sendmail(postfix)
+SMTP_ADDRESS=
+SMTP_PORT=1025
+SMTP_USERNAME=
+SMTP_PASSWORD=
+# plain,login,cram_md5
+SMTP_AUTHENTICATION=
+SMTP_ENABLE_STARTTLS_AUTO=true
+# Can be: 'none', 'peer', 'client_once', 'fail_if_no_peer_cert', see http://api.rubyonrails.org/classes/ActionMailer/Base.html
+SMTP_OPENSSL_VERIFY_MODE=peer
+# Comment out the following environment variables if required by your SMTP server
+# SMTP_TLS=
+# SMTP_SSL=
+# SMTP_OPEN_TIMEOUT
+# SMTP_READ_TIMEOUT
+
+# Mail Incoming
+# This is the domain set for the reply emails when conversation continuity is enabled
+MAILER_INBOUND_EMAIL_DOMAIN=
+# Set this to the appropriate ingress channel with regards to incoming emails
+# Possible values are :
+# relay for Exim, Postfix, Qmail
+# mailgun for Mailgun
+# mandrill for Mandrill
+# postmark for Postmark
+# sendgrid for Sendgrid
+RAILS_INBOUND_EMAIL_SERVICE=
+# Use one of the following based on the email ingress service
+# Ref: https://edgeguides.rubyonrails.org/action_mailbox_basics.html
+# Set this to a password of your choice and use it in the Inbound webhook
+RAILS_INBOUND_EMAIL_PASSWORD=
+
+MAILGUN_INGRESS_SIGNING_KEY=
+MANDRILL_INGRESS_API_KEY=
+
+# Creating Your Inbound Webhook Instructions for Postmark and Sendgrid:
+# Inbound webhook URL format:
+#    https://actionmailbox:[YOUR_RAILS_INBOUND_EMAIL_PASSWORD]@[YOUR_CHATWOOT_DOMAIN.COM]/rails/action_mailbox/[RAILS_INBOUND_EMAIL_SERVICE]/inbound_emails
+# Note: Replace the values inside the brackets; do not include the brackets themselves.
+# Example: https://actionmailbox:mYRandomPassword3@chatwoot.example.com/rails/action_mailbox/postmark/inbound_emails
+# For Postmark
+# Ensure the 'Include raw email content in JSON payload' checkbox is selected in the inbound webhook section.
+
+# Storage
+ACTIVE_STORAGE_SERVICE=local
+
+# Amazon S3
+# documentation: https://www.chatwoot.com/docs/configuring-s3-bucket-as-cloud-storage
+S3_BUCKET_NAME=
+AWS_ACCESS_KEY_ID=
+AWS_SECRET_ACCESS_KEY=
+AWS_REGION=
+
+# Log settings
+# Disable if you want to write logs to a file
+RAILS_LOG_TO_STDOUT=true
+LOG_LEVEL=info
+LOG_SIZE=500
+# Configure this environment variable if you want to use lograge instead of rails logger
+#LOGRAGE_ENABLED=true
+
+### This environment variables are only required if you are setting up social media channels
+
+# Facebook
+# documentation: https://www.chatwoot.com/docs/facebook-setup
+FB_VERIFY_TOKEN=
+FB_APP_SECRET=
+FB_APP_ID=
+
+# https://developers.facebook.com/docs/messenger-platform/instagram/get-started#app-dashboard
+IG_VERIFY_TOKEN=
+
+# Twitter
+# documentation: https://www.chatwoot.com/docs/twitter-app-setup
+TWITTER_APP_ID=
+TWITTER_CONSUMER_KEY=
+TWITTER_CONSUMER_SECRET=
+TWITTER_ENVIRONMENT=
+
+#slack integration
+SLACK_CLIENT_ID=
+SLACK_CLIENT_SECRET=
+
+# Google OAuth
+GOOGLE_OAUTH_CLIENT_ID=
+GOOGLE_OAUTH_CLIENT_SECRET=
+GOOGLE_OAUTH_CALLBACK_URL=
+
+### Change this env variable only if you are using a custom build mobile app
+## Mobile app env variables
+IOS_APP_ID=L7YLMN4634.com.chatwoot.app
+ANDROID_BUNDLE_ID=com.chatwoot.app
+
+# https://developers.google.com/android/guides/client-auth (use keytool to print the fingerprint in the first section)
+ANDROID_SHA256_CERT_FINGERPRINT=AC:73:8E:DE:EB:56:EA:CC:10:87:02:A7:65:37:7B:38:D4:5D:D4:53:F8:3B:FB:D3:C6:28:64:1D:AA:08:1E:D8
+
+### Smart App Banner
+# https://developer.apple.com/library/archive/documentation/AppleApplications/Reference/SafariWebContent/PromotingAppswithAppBanners/PromotingAppswithAppBanners.html
+# You can find your app-id in https://itunesconnect.apple.com
+#IOS_APP_IDENTIFIER=1495796682
+
+## Push Notification
+## generate a new key value here : https://d3v.one/vapid-key-generator/
+# VAPID_PUBLIC_KEY=
+# VAPID_PRIVATE_KEY=
+#
+# for mobile apps
+# FCM_SERVER_KEY=
+
+### APM and Error Monitoring configurations
+## Elastic APM
+## https://www.elastic.co/guide/en/apm/agent/ruby/current/getting-started-rails.html
+# ELASTIC_APM_SERVER_URL=
+# ELASTIC_APM_SECRET_TOKEN=
+
+## Sentry
+# SENTRY_DSN=
+
+
+## Scout
+## https://scoutapm.com/docs/ruby/configuration
+# SCOUT_KEY=YOURKEY
+# SCOUT_NAME=YOURAPPNAME (Production)
+# SCOUT_MONITOR=true
+
+## NewRelic
+# https://docs.newrelic.com/docs/agents/ruby-agent/configuration/ruby-agent-configuration/
+# NEW_RELIC_LICENSE_KEY=
+# Set this to true to allow newrelic apm to send logs.
+# This is turned off by default.
+# NEW_RELIC_APPLICATION_LOGGING_ENABLED=
+
+## Datadog
+## https://github.com/DataDog/dd-trace-rb/blob/master/docs/GettingStarted.md#environment-variables
+# DD_TRACE_AGENT_URL=
+
+# MaxMindDB API key to download GeoLite2 City database
+# IP_LOOKUP_API_KEY=
+
+## Rack Attack configuration
+## To prevent and throttle abusive requests
+# ENABLE_RACK_ATTACK=true
+# RACK_ATTACK_LIMIT=300
+# ENABLE_RACK_ATTACK_WIDGET_API=true
+CONVERSATION_MESSAGE_PER_MINUTE_LIMIT=3000
+
+## Running chatwoot as an API only server
+## setting this value to true will disable the frontend dashboard endpoints
+# CW_API_ONLY_SERVER=false
+
+## Development Only Config
+# if you want to use letter_opener for local emails
+# LETTER_OPENER=true
+# meant to be used in github codespaces
+# WEBPACKER_DEV_SERVER_PUBLIC=
+
+# If you want to use official mobile app,
+# the notifications would be relayed via a Chatwoot server
+ENABLE_PUSH_RELAY_SERVER=true
+
+# Stripe API key
+STRIPE_SECRET_KEY=
+STRIPE_WEBHOOK_SECRET=
+
+# Set to true if you want to upload files to cloud storage using the signed url
+# Make sure to follow https://edgeguides.rubyonrails.org/active_storage_overview.html#cross-origin-resource-sharing-cors-configuration on the cloud storage after setting this to true.
+DIRECT_UPLOADS_ENABLED=
+
+#MS OAUTH creds
+AZURE_APP_ID=
+AZURE_APP_SECRET=
+
+## Advanced configurations
+## Change these values to fine tune performance
+# control the concurrency setting of sidekiq
+# SIDEKIQ_CONCURRENCY=10
+
+
+# AI powered features
+## OpenAI key
+# OPENAI_API_KEY=
+
+# Housekeeping/Performance related configurations
+# Set to true if you want to remove stale contact inboxes
+# contact_inboxes with no conversation older than 90 days will be removed
+# REMOVE_STALE_CONTACT_INBOX_JOB_STATUS=false
+

docker-compose/chatwoot/.waha.env

@@ -0,0 +1,128 @@
+# WAHA - WhatsApp HTTP API
+#
+# https://waha.devlike.pro/docs/how-to/config/
+#
+
+# ====================
+# ===== SECURITY =====
+# ====================
+WAHA_API_KEY_PLAIN=00000000000000000000000000000000
+WAHA_API_KEY=00000000000000000000000000000000
+WAHA_DASHBOARD_USERNAME=admin
+WAHA_DASHBOARD_PASSWORD=11111111111111111111111111111111
+WHATSAPP_SWAGGER_USERNAME=admin
+WHATSAPP_SWAGGER_PASSWORD=11111111111111111111111111111111
+
+# Disable Dashboard or Swagger
+WAHA_DASHBOARD_ENABLED=True
+WHATSAPP_SWAGGER_ENABLED=True
+
+# ==================
+# ===== COMMON =====
+# ==================
+# Base URL for the API (used for webhooks, file URLs, etc.)
+WAHA_BASE_URL=http://waha:3000
+WAHA_PUBLIC_URL=http://localhost:3000
+
+# Server configuration (if you need to customize hostname/port)
+# WHATSAPP_API_SCHEMA=http
+# WHATSAPP_API_PORT=3000
+# WHATSAPP_API_HOSTNAME=localhost
+
+# WhatsApp engine (WEBJS is default, GOWS or NOWEB for better performance)
+WHATSAPP_DEFAULT_ENGINE=GOWS
+
+# WAHA_CLIENT_DEVICE_NAME=YourApp
+
+# =================
+# ===== APPS ======
+# =================
+WAHA_APPS_ENABLED=True
+REDIS_URL=redis://:redis@redis:6379
+
+# ===================
+# ===== LOGGING =====
+# ===================
+# Log format: JSON (for log management systems) or PRETTY (for development)
+WAHA_LOG_FORMAT=JSON
+
+# Log level: info, debug, error, warn
+WAHA_LOG_LEVEL=info
+
+# Don't print QR codes in logs
+WAHA_PRINT_QR=False
+
+# =========================
+# ===== MEDIA STORAGE =====
+# =========================
+# Local storage (default)
+WAHA_MEDIA_STORAGE=LOCAL
+WHATSAPP_FILES_LIFETIME=1800
+WHATSAPP_FILES_FOLDER=/app/.media
+
+#
+# Media download settings
+#
+# Events (webhooks, websockets)
+# WAHA_EVENTS_DOWNLOAD_MEDIA=true
+# WAHA_EVENTS_DOWNLOAD_MEDIA_MIMETYPES=image/jpeg,image/png
+# API default behavior (GET /api/{session}/chats/{chatId}/messages, etc.)
+# WAHA_API_DOWNLOAD_MEDIA=true
+# WAHA_API_DOWNLOAD_MEDIA_MIMETYPES=image/jpeg,image/png
+
+# DEPRECATED - use WAHA_EVENTS_* and WAHA_API_* variables above
+# WHATSAPP_DOWNLOAD_MEDIA=true
+# WHATSAPP_FILES_MIMETYPES=image/jpeg,image/png
+
+# S3 storage (uncomment to use)
+# WAHA_MEDIA_STORAGE=S3
+# WAHA_S3_REGION=eu-west-2
+# WAHA_S3_BUCKET=waha
+# WAHA_S3_ACCESS_KEY_ID=minioadmin
+# WAHA_S3_SECRET_ACCESS_KEY=minioadmin
+# WAHA_S3_ENDPOINT=http://minio:9000
+# WAHA_S3_FORCE_PATH_STYLE=True
+# WAHA_S3_PROXY_FILES=True
+
+# PostgreSQL storage (uncomment to use)
+# WAHA_MEDIA_STORAGE=POSTGRESQL
+# WAHA_MEDIA_POSTGRESQL_URL=postgres://postgres:postgres@postgres:5432/postgres?sslmode=disable
+
+# ===========================
+# ===== SESSION STORAGE =====
+# ===========================
+# PostgreSQL for sessions (uncomment to use)
+WHATSAPP_SESSIONS_POSTGRESQL_URL=postgres://postgres:postgres@postgres:5432/postgres?sslmode=disable
+
+# MongoDB for sessions (uncomment to use)
+# WHATSAPP_SESSIONS_MONGO_URL=mongodb://mongouser:mongopassword@mongodb:27017
+
+
+# ==================================
+# ===== ADVANCED CONFIGURATION =====
+# ==================================
+
+# Timezone for screenshots and logs
+# TZ=Europe/Dublin
+
+# Session management
+# WHATSAPP_START_SESSION=session1,session2
+# WHATSAPP_RESTART_ALL_SESSIONS=False
+
+# Webhooks
+# WHATSAPP_HOOK_URL=https://webhook.site/11111111-1111-1111-1111-11111111
+# WHATSAPP_HOOK_EVENTS=session.status,message,message.reaction
+
+# Proxy configuration
+# WHATSAPP_PROXY_SERVER=proxy.example.com:3128
+# WHATSAPP_PROXY_SERVER_USERNAME=user
+# WHATSAPP_PROXY_SERVER_PASSWORD=pass
+
+# HTTPS configuration
+# !DEPRECATED!
+# Setup nginx reverse proxy to handle TLS connection
+# using Let's encrypt or self-issued certificate
+# WAHA_HTTPS_ENABLED=true
+# WAHA_HTTPS_PATH_KEY=/etc/letsencrypt/live/waha.example.pro/privkey.pem
+# WAHA_HTTPS_PATH_CERT=/etc/letsencrypt/live/waha.example.pro/cert.pem
+# WAHA_HTTPS_PATH_CA=/etc/letsencrypt/live/waha.example.pro/chain.pem

docker-compose/chatwoot/docker-compose.yaml

@@ -0,0 +1,98 @@
+services:
+  waha:
+    restart: always
+    image: devlikeapro/waha-plus
+    ports:
+      - '127.0.0.1:3000:3000/tcp'
+    volumes:
+      - './sessions:/app/.sessions' # required for WAHA Core only
+      - './media:/app/.media'
+    env_file:
+      - .waha.env
+    depends_on:
+      - postgres
+      - redis
+      - chatwoot
+      - chatwoot-sidekiq
+    logging:
+      driver: 'json-file'
+      options:
+        max-size: '100m'
+        max-file: '10'
+    dns:
+      - 1.1.1.1
+      - 8.8.8.8
+
+  base: &base
+    image: chatwoot/chatwoot:v4.12.1
+    env_file: .chatwoot.env ## Change this file for customized env variables
+    volumes:
+      - chatwoot_storage:/app/storage
+    extra_hosts:
+      - 'host.docker.internal:host-gateway'
+    logging:
+      driver: 'json-file'
+      options:
+        max-size: '100m'
+        max-file: '10'
+
+  chatwoot:
+    <<: *base
+    depends_on:
+      - postgres
+      - redis
+    ports:
+      - '127.0.0.1:3009:3009'
+    environment:
+      - NODE_ENV=production
+      - RAILS_ENV=production
+      - INSTALLATION_ENV=docker
+    entrypoint: docker/entrypoints/rails.sh
+    command: ['bundle', 'exec', 'rails', 's', '-p', '3009', '-b', '0.0.0.0']
+    restart: always
+
+  chatwoot-sidekiq:
+    <<: *base
+    depends_on:
+      - postgres
+      - redis
+    environment:
+      - NODE_ENV=production
+      - RAILS_ENV=production
+      - INSTALLATION_ENV=docker
+    command: ['bundle', 'exec', 'sidekiq', '-C', 'config/sidekiq.yml']
+    restart: always
+
+  postgres:
+    image: pgvector/pgvector:pg16
+    restart: always
+    ports:
+      - '127.0.0.1:5432:5432'
+    volumes:
+      - chatwoot_pg_data:/var/lib/postgresql/data
+    environment:
+      - POSTGRES_DB=chatwoot
+      - POSTGRES_USER=postgres
+      # Please provide your own password.
+      - POSTGRES_PASSWORD=postgres
+
+  redis:
+    image: redis:alpine
+    restart: always
+    command:
+      - 'sh'
+      - '-c'
+      - >
+        redis-server --bind 0.0.0.0 --port 6379 --requirepass
+        ${REDIS_PASSWORD:-redis} --timeout 300 --tcp-keepalive 60 --save 900 1
+        --save 300 10 --save 60 10000 --appendonly yes --appendfsync everysec
+    env_file: .chatwoot.env
+    volumes:
+      - chatwoot_redis:/data
+    ports:
+      - '127.0.0.1:6379:6379'
+
+volumes:
+  chatwoot_pg_data: {}
+  chatwoot_redis: {}
+  chatwoot_storage: {}

docker-compose/docker-compose.workers.yaml

@@ -0,0 +1,97 @@
+# https://waha.devlike.pro/docs/how-to/install/
+services:
+  # Just to connect
+  waha-dashboard:
+    restart: unless-stopped
+    image: devlikeapro/waha-plus:latest
+    ports:
+      - '127.0.0.1:3000:3000/tcp'
+    env_file:
+      - .env
+    environment:
+      - WAHA_WORKER_ID=waha-dashboard
+
+  waha1:
+    restart: unless-stopped
+    image: devlikeapro/waha-plus:latest
+    ports:
+      - '127.0.0.1:3001:3000/tcp'
+    volumes:
+      - './media:/app/.media'
+    env_file:
+      - .env
+    environment:
+      - WAHA_WORKER_ID=waha1
+      - WAHA_BASE_URL=http://localhost:3001
+      - WHATSAPP_DEFAULT_ENGINE=NOWEB
+      # MongoDB
+      - WHATSAPP_SESSIONS_MONGO_URL=mongodb://mongodb:27017
+      # S3
+      - WAHA_MEDIA_STORAGE=S3
+      - WAHA_S3_REGION=eu-west-2
+      - WAHA_S3_BUCKET=waha
+      - WAHA_S3_ACCESS_KEY_ID=minioadmin
+      - WAHA_S3_SECRET_ACCESS_KEY=minioadmin
+      - WAHA_S3_ENDPOINT=http://minio:9000 # Not required if you're using AWS S3
+      - WAHA_S3_FORCE_PATH_STYLE=True # Required for Minio
+      - WAHA_S3_PROXY_FILES=True # Required for docker-compose setup
+
+  waha2:
+    restart: unless-stopped
+    image: devlikeapro/waha-plus:latest
+    ports:
+      - '127.0.0.1:3002:3000/tcp'
+    volumes:
+      - './media:/app/.media'
+    env_file:
+      - .env
+    environment:
+      - WAHA_WORKER_ID=waha2
+      - WAHA_BASE_URL=http://localhost:3002
+      - WHATSAPP_DEFAULT_ENGINE=NOWEB
+      # MongoDB
+      - WHATSAPP_SESSIONS_MONGO_URL=mongodb://mongodb:27017
+      # S3
+      - WAHA_MEDIA_STORAGE=S3
+      - WAHA_S3_REGION=eu-west-2
+      - WAHA_S3_BUCKET=waha
+      - WAHA_S3_ACCESS_KEY_ID=minioadmin
+      - WAHA_S3_SECRET_ACCESS_KEY=minioadmin
+      - WAHA_S3_ENDPOINT=http://minio:9000 # Not required if you're using AWS S3
+      - WAHA_S3_FORCE_PATH_STYLE=True # Required for Minio
+      - WAHA_S3_PROXY_FILES=True # Required for docker-compose setup
+
+  # NOTE: Only if you're using MongoDB
+  # https://waha.devlike.pro/docs/how-to/storages/#sessions---mongodb
+  # Comment this block if you're not using MongoDB
+  mongodb:
+    image: mongo
+    container_name: mongodb
+    ports:
+      - '127.0.0.1:27017:27017/tcp'
+    volumes:
+      - mongodb_data:/data/db
+    restart: always
+
+  # NOTE: Only if you're using S3 to save media files
+  # https://waha.devlike.pro/docs/how-to/storages/#media---s3
+  # Comment this block if you're using S3
+  minio:
+    image: quay.io/minio/minio
+    container_name: minio
+    restart: always
+    ports:
+      - '127.0.0.1:9000:9000'
+      - '127.0.0.1:9001:9001'
+    environment:
+      MINIO_REGION: 'eu-west-2'
+      MINIO_ROOT_USER: 'minioadmin'
+      MINIO_ROOT_PASSWORD: 'minioadmin'
+    volumes:
+      - minio_data:/data
+    command: server /data --console-address ":9001"
+
+volumes:
+  # NOTE: Only if you're using MongoDB
+  mongodb_data: {}
+  minio_data: {}

docker-compose/n8n/docker-compose.yaml

@@ -0,0 +1,34 @@
+services:
+  waha:
+    restart: always
+    container_name: waha
+    # image: devlikeapro/waha:latest
+    image: devlikeapro/waha-plus:latest
+    ports:
+      - '3000:3000/tcp'
+    volumes:
+      - './sessions:/app/.sessions'
+      - './media:/app/.media'
+    environment:
+      - WAHA_API_KEY=321
+      - WAHA_DASHBOARD_USERNAME=admin
+      - WAHA_DASHBOARD_PASSWORD=admin
+      - WHATSAPP_DEFAULT_ENGINE=WEBJS
+      - WAHA_PRINT_QR=False
+      - WAHA_MEDIA_STORAGE=LOCAL
+      - WHATSAPP_FILES_LIFETIME=0
+      - WHATSAPP_FILES_FOLDER=/app/.media
+
+  n8n:
+    image: docker.n8n.io/n8nio/n8n
+    container_name: n8n
+    restart: always
+    environment:
+      - WEBHOOK_URL=http://n8n:5678
+    ports:
+      - '5678:5678'
+    volumes:
+      - n8n_data:/home/node/.n8n
+
+volumes:
+  n8n_data: {}

docker-compose/test/docker-compose.yaml

@@ -25,20 +25,19 @@ services:
       - './.sessions:/app/.sessions'
     environment:
       # Environment variables from https://waha.devlike.pro/docs/how-to/config/
-      # - WHATSAPP_RESTART_ALL_SESSIONS=True
       # - WHATSAPP_HOOK_URL=https://webhook.site/11111111-1111-1111-1111-11111111
       # - WHATSAPP_HOOK_EVENTS=message
       # - WHATSAPP_API_HOSTNAME=localhost
       - WHATSAPP_DEFAULT_ENGINE=WEBJS
-      - WHATSAPP_API_KEY=321
+      - WAHA_API_KEY=321
       # Username and password for Swagger
       - WHATSAPP_SWAGGER_USERNAME=swagger
       - WHATSAPP_SWAGGER_PASSWORD=admin
       # Username and password for WAHA Dashboard
       # you can use the same username and password for both Swagger and Dashboard
       # Default - waha / waha
-      - WAHA_DASHBOARD_USERNAME=waha
-      - WAHA_DASHBOARD_PASSWORD=waha
+      - WAHA_DASHBOARD_USERNAME=admin
+      - WAHA_DASHBOARD_PASSWORD=admin
       # Engine specific environment variables
       # - WAHA_WEBJS_WEB_VERSION=2.2412.54-videofix
     restart: always
@@ -54,10 +53,9 @@ services:
       - './.sessions:/app/.sessions'
     environment:
       # Environment variables from https://waha.devlike.pro/docs/how-to/config/
-      # - WHATSAPP_RESTART_ALL_SESSIONS=True
       # - WHATSAPP_HOOK_URL=https://webhook.site/11111111-1111-1111-1111-11111111
       # - WHATSAPP_HOOK_EVENTS=message
-      # - WHATSAPP_API_KEY=321
+      # - WAHA_API_KEY=321
       # - WHATSAPP_SWAGGER_USERNAME=admin
       # - WHATSAPP_SWAGGER_PASSWORD=123
       # - WAHA_DASHBOARD_USERNAME=admin

entrypoint.sh

@@ -0,0 +1,82 @@
+#!/bin/sh
+
+
+#
+# Calculate UV_THREADPOOL_SIZE based on number of CPUs
+#
+# Try to get CPU count using Node.js, fallback to 1 if it fails
+cpus=$(node -e "const os = require('os'); console.log(os.cpus().length);" 2>/dev/null) || cpus=1
+# Make sure cpus is a number, default to 1 if not
+case $cpus in
+  ''|*[!0-9]*) cpus=1 ;;
+esac
+uv_threadpool_size=$(($cpus * 2))
+
+# Check if uv_threadpool_size is less than 4 (default), set it to 4 if it is
+if [ "$uv_threadpool_size" -lt 4 ]; then
+  uv_threadpool_size=4
+fi
+
+# Set UV_THREADPOOL_SIZE as an environment variable
+export UV_THREADPOOL_SIZE="${UV_THREADPOOL_SIZE:-$uv_threadpool_size}"
+
+#
+# Handle API key hashing
+#
+# Save WHATSAPP_API_KEY or WAHA_API_KEY in a variable (WHATSAPP_API_KEY has priority)
+if [ -n "$WHATSAPP_API_KEY" ]; then
+  key="$WHATSAPP_API_KEY"
+elif [ -n "$WAHA_API_KEY" ]; then
+  key="$WAHA_API_KEY"
+fi
+
+# Unset both environment variables
+unset WHATSAPP_API_KEY
+unset WAHA_API_KEY
+
+# Process the key if it exists
+if [ -n "$key" ]; then
+  # Check if key is already hashed
+  if echo "$key" | grep -q "^sha512:"; then
+    # If already hashed, use it as is
+    export WAHA_API_KEY="$key"
+  else
+    # Hash the key using sha512sum
+    HASHED_KEY=$(echo -n "$key" | sha512sum | awk '{print $1}')
+    export WAHA_API_KEY="sha512:$HASHED_KEY"
+  fi
+fi
+
+#
+# xvfb-run
+#
+USE_XVFB=false
+
+# Check WAHA_RUN_XVFB parameter - only test for "false" case, treat all others as True
+if [ "$WAHA_RUN_XVFB" = "false" ] || [ "$WAHA_RUN_XVFB" = "False" ] || [ "$WAHA_RUN_XVFB" = "0" ]; then
+  # Explicitly disabled by user
+  echo "WAHA_RUN_XVFB value: $WAHA_RUN_XVFB - xvfb is disabled"
+  USE_XVFB=false
+else
+  # Check engine and run test if it's WEBJS or not specified
+  if [ -z "$WHATSAPP_DEFAULT_ENGINE" ] || [ "$WHATSAPP_DEFAULT_ENGINE" = "WEBJS" ]; then
+    # Try to run xvfb-run with a test command
+    if xvfb-run --auto-servernum echo "xvfb-run is working!"; then
+      USE_XVFB=true
+    else
+      echo "xvfb-run test failed, do not run it"
+      USE_XVFB=false
+    fi
+  fi
+fi
+
+#
+# Start your application using node with exec to ensure proper signal handling
+#
+if [ "$USE_XVFB" = "true" ]; then
+  echo "Executing node with xvfb-run..."
+  exec xvfb-run --auto-servernum node dist/main
+else
+  echo "Executing node without xvfb-run..."
+  exec node dist/main
+fi

examples/python/README.md

@@ -50,8 +50,8 @@ docker run -it --rm --network=host -e WHATSAPP_HOOK_URL=http://localhost:5000/bo
 
 2. Open Swagger API in the browser http://localhost:3000/
 3. Start session and scan QR code in swagger
-   1. Find `POST /api/session/start` request press **Try it out** and
-      **Execute** it with `default` session name
+   1. Find `POST /api/sessions/` request press **Try it out** and **Execute** it
+      with `default` session name
    2. Find `GET /api/screenshot` and execute it - it must show QR code
    3. Scan QR code on your mobile WhatsApp application (that installed on your
       phone)

nest-cli.json

@@ -3,7 +3,13 @@
   "sourceRoot": "src",
   "compilerOptions": {
     "plugins": ["@nestjs/swagger"],
-    "assets": ["dashboard/**", "core/engines/webjs/*", "plus/engines/webjs/*"],
-    "watchAssets": true
+    "assets": [
+      { "include": "dashboard/**", "watchAssets": false },
+      { "include": "core/engines/webjs/*", "watchAssets": true },
+      { "include": "plus/engines/webjs/*", "watchAssets": true },
+      { "include": "apps/chatwoot/i18n/locales/*.yaml", "watchAssets": true },
+      { "include": "apps/chatwoot/i18n/locales/*.yml", "watchAssets": true }
+    ],
+    "watchAssets": false
   }
 }

package.json

@@ -14,101 +14,204 @@
     "start:debug": "nest start --debug --watch",
     "start:prod": "node dist/main",
     "start:prod-exit": "node dist/main",
-    "lint": "eslint \"{src,apps,libs,test}/**/*.ts\" --fix --max-warnings=0",
-    "test": "jest",
-    "test:watch": "jest --watch",
-    "test:cov": "jest --coverage",
-    "test:debug": "node --inspect-brk -r tsconfig-paths/register -r ts-node/register node_modules/.bin/jest --runInBand",
-    "test:e2e": "jest --config ./test/jest-e2e.json"
+    "lint": "oxlint --deny-warnings",
+    "lint-fix": "oxlint --fix --deny-warnings",
+    "test": "yarn test:unit",
+    "test:watch": "jest --selectProjects unit --watch",
+    "test:cov": "jest --selectProjects unit --coverage",
+    "test:debug": "node --inspect-brk -r tsconfig-paths/register -r ts-node/register node_modules/.bin/jest --selectProjects unit --runInBand",
+    "test:unit": "jest --selectProjects unit",
+    "test:e2e": "jest --selectProjects e2e",
+    "test:e8e": "yarn test:e2e",
+    "test:all": "yarn test:unit && yarn test:e8e",
+    "gows:proto:fetch": "node scripts/gows-proto.js fetch",
+    "gows:proto:build": "node scripts/gows-proto.js build",
+    "gows:proto": "yarn gows:proto:fetch && yarn gows:proto:build"
   },
   "dependencies": {
-    "@adiwajshing/baileys": "github:devlikeapro/Baileys#fork-master-channels",
+    "@adiwajshing/baileys": "github:devlikeapro/Baileys#fork-master-2026-04-28",
     "@adiwajshing/keyed-db": "^0.2.4",
+    "@aws-sdk/client-s3": "^3.633.0",
+    "@aws-sdk/s3-request-presigner": "^3.633.0",
+    "@bull-board/api": "^6.9.1",
+    "@bull-board/express": "^6.9.1",
+    "@bull-board/nestjs": "^6.9.1",
+    "@casl/ability": "^6.8.0",
+    "@figuro/chatwoot-sdk": "^1.1.17",
+    "@liaoliaots/nestjs-redis": "^9",
+    "@lottiefiles/dotlottie-web": "^0.72.1",
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "@napi-rs/canvas": "^1.0.0",
     "@nestjs/axios": "^3.0.2",
-    "@nestjs/common": "^9.0.9",
-    "@nestjs/config": "^0.5.0",
-    "@nestjs/core": "^9.0.9",
-    "@nestjs/passport": "^9.0.0",
-    "@nestjs/platform-express": "^9.0.9",
-    "@nestjs/platform-ws": "^9.0.9",
-    "@nestjs/serve-static": "^2.1.3",
+    "@nestjs/bullmq": "^11.0.2",
+    "@nestjs/common": "^11.0.0",
+    "@nestjs/config": "^3.2.3",
+    "@nestjs/core": "^11.0.0",
+    "@nestjs/passport": "^11.0.0",
+    "@nestjs/platform-express": "^11.1.5",
+    "@nestjs/platform-ws": "^11.0.0",
+    "@nestjs/serve-static": "^5.0.0",
     "@nestjs/swagger": "^7.1.11",
     "@nestjs/terminus": "^10.2.3",
-    "@nestjs/websockets": "^9.0.9",
+    "@nestjs/websockets": "^11.0.0",
+    "@opentelemetry/api": "^1.9.1",
+    "@opentelemetry/instrumentation-http": "^0.221.0",
+    "@opentelemetry/instrumentation-pino": "^0.67.0",
+    "@opentelemetry/sdk-node": "^0.221.0",
+    "@opentelemetry/sdk-trace": "^2.10.0",
+    "@prometheus-io/client": "^0.16.1",
     "@types/better-sqlite3": "^7.6.10",
     "@types/lodash": "^4.14.194",
+    "@types/mustache": "^4.2.5",
+    "@types/passport": "^1.0.17",
+    "@types/sqlite3": "^5.1.0",
     "@types/ws": "^8.5.4",
+    "@wppconnect-team/wppconnect": "github:wppconnect-team/wppconnect#master",
+    "@wppconnect/wa-js": "github:wppconnect-team/wa-js#main",
     "adm-zip": "0.5.10",
+    "agentkeepalive": "^4.5.0",
     "async-lock": "^1.4.1",
-    "better-sqlite3": "9.6.0",
+    "audio-decode": "^2.2.2",
+    "axios": "^1.19.0",
+    "axios-retry": "^4.5.0",
+    "better-sqlite3": "^12.4.1",
+    "bullmq": "^5.48.1",
     "check-disk-space": "^3.4.0",
     "chokidar": "^3.6.0",
     "class-transformer": "^0.5.1",
     "class-validator": "0.14.0",
-    "del": "^6.0.0",
+    "commander": "^14.0.1",
+    "del": "^8.0.0",
     "express-basic-auth": "^1.2.1",
     "file-type": "16.5.4",
+    "fs-extra": "^11.2.0",
+    "google-protobuf": "^3.21.4",
     "https-proxy-agent": "^7.0.0",
+    "ical.js": "^2.2.1",
+    "ioredis": "^5",
+    "joi": "^17.13.3",
     "knex": "^3.1.0",
     "libphonenumber-js": "^1.10.36",
+    "libsignal": "github:WhiskeySockets/libsignal-node#master",
     "link-preview-js": "^3.0.4",
     "lodash": "^4.17.21",
+    "long": "^5.3.2",
     "mime-types": "^2.1.27",
-    "mongodb": "^6.3.0",
+    "mongodb": "6.9.0",
+    "ms": "^2.1.3",
+    "mustache": "^4.2.0",
     "nestjs-pino": "^4.1.0",
-    "passport": "^0.6.0",
+    "node-cache": "5.1.2",
+    "node-webpmux": "^3.2.1",
+    "passport": "^0.7.0",
     "passport-headerapikey": "^1.2.2",
+    "pg": "^8.13.1",
+    "pg-copy-streams": "^6.0.0",
     "pino-http": "^10.2.0",
     "pino-pretty": "^11.2.1",
-    "puppeteer": "^21.0.0",
+    "pretty-bytes": "5.6.0",
+    "promise-retry": "^2.0.1",
+    "puppeteer": "^25.10.0",
     "qrcode": "^1.5.1",
     "qrcode-terminal": "^0.12.0",
     "reflect-metadata": "^0.1.13",
-    "request": "^2.88.2",
-    "requestretry": "^4.1.1",
-    "rimraf": "^3.0.2",
-    "rxjs": "^7.1.0",
-    "sharp": "^0.33.4",
+    "rimraf": "^4.3.0",
+    "rxjs": "^7.8.1",
+    "sharp": "^0.34.5",
+    "shell-quote": "^1.8.3",
+    "sqlite3": "^5.1.7",
     "swagger-ui-express": "^4.1.4",
-    "venom-bot": "5.0.1",
-    "whatsapp-web.js": "github:devlikeapro/whatsapp-web.js#fork-webpack-exodus-channels"
+    "tapable": "^2.2.2",
+    "ulid": "^2.3.0",
+    "undici": "^7.16.0",
+    "uniqid": "^5.4.0",
+    "user-agents": "^1.1.669",
+    "whatsapp-web.js": "github:devlikeapro/whatsapp-web.js#fork-main-2026-06-26",
+    "write-file-atomic": "^6.0.0",
+    "yaml": "^2.7.1",
+    "zod": "^4.3.6"
+  },
+  "optionalDependencies": {
+    "bufferutil": "^4.0.8"
+  },
+  "resolutions": {
+    "typescript": "5.9.2",
+    "bufferutil": "^4.0.8",
+    "ws": "^8.18.0",
+    "puppeteer": "^25.10.0",
+    "whatwg-url": "13.0.0",
+    "axios": "^1.19.0",
+    "whatsapp-rust-bridge": "npm:@devlikeapro/whatsapp-rust-bridge@0.5.2",
+    "sharp": "0.35.3"
   },
   "devDependencies": {
-    "@nestjs/cli": "^9.0.0",
-    "@nestjs/schematics": "^9.0.1",
-    "@nestjs/testing": "^9.0.9",
+    "@grpc/grpc-js": "^1.14.1",
+    "@grpc/proto-loader": "^0.8.0",
+    "@nestjs/cli": "^11.0.0",
+    "@nestjs/schematics": "^11.0.0",
+    "@nestjs/testing": "^11.0.0",
     "@types/express": "^4.17.3",
     "@types/jest": "26.0.10",
     "@types/node": "^18.14.2",
+    "@types/node-fetch": "^2.6.13",
+    "@types/semver": "^7.7.0",
     "@types/supertest": "^2.0.8",
-    "@typescript-eslint/eslint-plugin": "3.9.1",
-    "@typescript-eslint/parser": "3.9.1",
-    "eslint": "7.7.0",
-    "eslint-config-prettier": "^6.10.0",
-    "eslint-plugin-import": "^2.20.1",
-    "eslint-plugin-simple-import-sort": "^10.0.0",
+    "@types/user-agents": "^1",
+    "dotenv": "^17.2.3",
+    "grpc-tools": "^1.13.0",
     "jest": "^29.7.0",
+    "oxlint": "^1.13.0",
     "prettier": "^1.19.1",
+    "protoc-gen-ts": "^0.8.7",
     "supertest": "^4.0.2",
     "ts-jest": "^29.1.3",
     "ts-loader": "^6.2.1",
-    "ts-node": "^10.9.1",
+    "ts-node": "^10.9.2",
     "tsconfig-paths": "^4.1.0",
-    "typescript": "^4.8.4"
+    "typescript": "5.9.2"
   },
   "jest": {
-    "moduleFileExtensions": [
-      "js",
-      "json",
-      "ts"
-    ],
-    "rootDir": "src",
-    "testRegex": ".test.ts$",
-    "transform": {
-      "^.+\\.(t|j)s$": "ts-jest"
-    },
-    "coverageDirectory": "../coverage",
-    "testEnvironment": "node"
+    "projects": [
+      {
+        "displayName": "unit",
+        "moduleFileExtensions": [
+          "js",
+          "json",
+          "ts"
+        ],
+        "rootDir": "src",
+        "moduleNameMapper": {
+          "^@waha/(.*)$": "<rootDir>/$1"
+        },
+        "testRegex": ".test.ts$",
+        "testPathIgnorePatterns": [
+          "/__tests__/e2e/"
+        ],
+        "transform": {
+          "^.+\\.(t|j)s$": "ts-jest"
+        },
+        "coverageDirectory": "../coverage",
+        "testEnvironment": "node"
+      },
+      {
+        "displayName": "e2e",
+        "moduleFileExtensions": [
+          "js",
+          "json",
+          "ts"
+        ],
+        "rootDir": "src",
+        "moduleNameMapper": {
+          "^@waha/(.*)$": "<rootDir>/$1"
+        },
+        "testRegex": "__tests__/e2e/.*\\.test\\.ts$",
+        "transform": {
+          "^.+\\.(t|j)s$": "ts-jest"
+        },
+        "coverageDirectory": "../coverage",
+        "testEnvironment": "node"
+      }
+    ]
   },
-  "packageManager": "yarn@3.6.3"
+  "packageManager": "yarn@4.17.1"
 }

prepare-chatgpt.sh

@@ -0,0 +1,22 @@
+#!/bin/bash
+
+# Set source and output file
+SOURCE_DIR="src"
+OUTPUT_DIR="$HOME/Downloads/chatgpt"
+OUTPUT_FILE="$OUTPUT_DIR/waha.ts"
+
+# Create or clear the output file
+rm -f "$OUTPUT_FILE"
+touch "$OUTPUT_FILE"
+
+# Find all .md files in the source directory and combine them
+find "$SOURCE_DIR" -type f -name "*.ts" | while read -r file; do
+  # Add file name  to OUTPUT_FILE
+  echo "\n-------" >> "$OUTPUT_FILE"
+  echo "File: $file" >> "$OUTPUT_FILE"
+  echo "-------\n" >> "$OUTPUT_FILE"
+  # Append the content of the file to the output file
+  cat "$file" >> "$OUTPUT_FILE"
+done
+
+echo "All .ts files combined into $OUTPUT_FILE with separators."

scripts/_find_unused_i18n.js

@@ -0,0 +1,72 @@
+#!/usr/bin/env node
+const { readFileSync } = require('fs');
+const { spawnSync } = require('child_process');
+const path = require('path');
+const YAML = require('yaml');
+
+const repoRoot = path.resolve(__dirname, '..');
+const enPath = path.join(repoRoot, 'src/apps/chatwoot/i18n/locales/en-US.yaml');
+const contents = readFileSync(enPath, 'utf8');
+const document = YAML.parse(contents);
+
+const flatten = (node, prefix = '') => {
+  if (node && typeof node === 'object' && !Array.isArray(node)) {
+    return Object.entries(node).reduce((acc, [key, value]) => {
+      const next = prefix ? `${prefix}.${key}` : key;
+      return acc.concat(flatten(value, next));
+    }, []);
+  }
+
+  return [prefix];
+};
+
+const allKeys = flatten(document).filter(Boolean);
+
+const ignoredPrefixes = ['datetime.', 'locale.'];
+
+const ignored = new Set();
+const unused = [];
+
+const searchRoots = ['src', 'tests'];
+
+for (const key of allKeys) {
+  if (
+    ignoredPrefixes.some((prefix) => key.startsWith(prefix)) ||
+    !key.includes('.')
+  ) {
+    ignored.add(key);
+    continue;
+  }
+
+  const result = spawnSync(
+    'rg',
+    [
+      '--files-with-matches',
+      '--fixed-strings',
+      key,
+      ...searchRoots,
+      '--glob',
+      '!apps/chatwoot/i18n/locales/*.yaml',
+    ],
+    {
+      cwd: repoRoot,
+      encoding: 'utf8',
+    },
+  );
+
+  if (result.status !== 0 || !result.stdout.trim()) {
+    unused.push(key);
+  }
+}
+
+const message = [
+  `Scanned ${allKeys.length} keys.`,
+  `Ignored ${ignored.size} keys (datetime.*, locale.*, or without dot).`,
+  unused.length
+    ? `Found ${unused.length} potentially unused keys:\n - ${unused.join(
+        '\n - ',
+      )}`
+    : 'No unused keys detected.',
+];
+
+console.log(message.join('\n'));

scripts/gows-proto.js

@@ -0,0 +1,144 @@
+// eslint-disable-next-line @typescript-eslint/no-var-requires
+const fs = require('fs');
+// eslint-disable-next-line @typescript-eslint/no-var-requires
+const path = require('path');
+// eslint-disable-next-line @typescript-eslint/no-var-requires
+const axios = require('axios');
+// eslint-disable-next-line @typescript-eslint/no-var-requires
+const { execSync } = require('child_process');
+// eslint-disable-next-line @typescript-eslint/no-var-requires
+const yargs = require('yargs');
+
+// Defaults
+const CONFIG_FILE = 'waha.config.json';
+// Load defaults from package.json
+gows = (() => {
+  try {
+    const config = JSON.parse(fs.readFileSync(CONFIG_FILE, 'utf8'));
+    return config.waha.gows || {};
+  } catch (error) {
+    return {};
+  }
+})();
+
+const DEFAULT_REPO = gows.repo;
+if (!DEFAULT_REPO) {
+  throw new Error(`Missing default repo in ${CONFIG_FILE}`);
+}
+const DEFAULT_REF = gows.ref;
+if (!DEFAULT_REF) {
+  throw new Error('Missing default ref in ${CONFIG_FILE}');
+}
+const DEFAULT_DIR = './src/core/engines/gows/proto';
+
+const PROTO_FILES = ['gows.proto'];
+const PROTO_OUTPUT = './src/core/engines/gows/grpc';
+
+// Helper function to clean directory
+function cleanDirectory(directory, suffix) {
+  if (!fs.existsSync(directory)) {
+    fs.mkdirSync(directory, { recursive: true });
+    return;
+  }
+
+  const files = fs.readdirSync(directory);
+  for (const file of files) {
+    const filePath = path.join(directory, file);
+    if (file.endsWith(suffix)) {
+      fs.unlinkSync(filePath);
+    }
+  }
+}
+
+// Helper function to download files
+async function downloadFiles(repo, ref, directory) {
+  for (const file of PROTO_FILES) {
+    const url = `https://github.com/${repo}/releases/download/${ref}/${file}`;
+    const filePath = path.join(directory, file);
+    try {
+      const response = await axios.get(url, { responseType: 'arraybuffer' });
+      fs.writeFileSync(filePath, response.data);
+      console.log(`Downloaded: ${file}`);
+    } catch (error) {
+      console.error(`Failed to download ${file}: ${error.message}`);
+    }
+  }
+}
+
+// Handler for fetch command
+async function handleFetch(repo, ref, dir) {
+  console.log(`Fetching .proto files from ${repo}@${ref} to ${dir}...`);
+  cleanDirectory(dir, '.proto');
+  await downloadFiles(repo, ref, dir);
+}
+
+// Handler for build command
+function handleBuild(dir) {
+  console.log('Building gRPC files...');
+  cleanDirectory(PROTO_OUTPUT);
+
+  const command = `grpc_tools_node_protoc \
+        --plugin=protoc-gen-ts=node_modules/.bin/protoc-gen-ts \
+        --plugin=protoc-gen-grpc=node_modules/.bin/grpc_tools_node_protoc_plugin \
+        --js_out=import_style=commonjs,binary:${PROTO_OUTPUT} \
+        --grpc_out=grpc_js:${PROTO_OUTPUT} \
+        --ts_out=grpc_js:${PROTO_OUTPUT} \
+        -I ${dir} ${dir}/gows.proto`;
+
+  try {
+    execSync(command, { stdio: 'inherit' });
+    console.log('gRPC files built successfully.');
+  } catch (error) {
+    console.error(`Failed to build gRPC files: ${error.message}`);
+  }
+}
+
+//
+// Commands
+//
+
+// fetch
+yargs.command(
+  'fetch',
+  'Fetch .proto files from GitHub',
+  (yargs) => {
+    yargs
+      .option('repo', {
+        describe: 'GitHub repository (owner/repo)',
+        type: 'string',
+        default: DEFAULT_REPO,
+      })
+      .option('ref', {
+        describe: 'Git reference (branch or commit SHA)',
+        type: 'string',
+        default: DEFAULT_REF,
+      })
+      .option('dir', {
+        describe: 'Directory to output .proto files',
+        type: 'string',
+        default: DEFAULT_DIR,
+      });
+  },
+  async (argv) => {
+    await handleFetch(argv.repo, argv.ref, argv.dir);
+  },
+);
+
+// build
+yargs.command(
+  'build',
+  'Build gRPC files from .proto files',
+  (yargs) => {
+    yargs.option('dir', {
+      describe: 'Directory containing .proto files',
+      type: 'string',
+      default: DEFAULT_DIR,
+    });
+  },
+  (argv) => {
+    handleBuild(argv.dir);
+  },
+);
+
+// Parse arguments
+yargs.parse();

scripts/init-waha.js

@@ -0,0 +1,106 @@
+#!/usr/bin/env node
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+
+const projectRoot = path.resolve(__dirname, '..');
+
+const args = process.argv.slice(2);
+const forceIndex = args.indexOf('--force');
+const forceOverwrite = forceIndex !== -1;
+
+if (forceOverwrite) {
+  args.splice(forceIndex, 1);
+}
+
+const folderArg = args[0] || '.';
+const sourceArgRaw = args[1];
+const targetArg = args[2] || '.env';
+
+const envDir = path.resolve(process.cwd(), folderArg);
+const sourceArg = sourceArgRaw || '.env.example';
+const templateBaseDir = sourceArgRaw ? envDir : projectRoot;
+const templatePath = path.isAbsolute(sourceArg)
+  ? sourceArg
+  : path.resolve(templateBaseDir, sourceArg);
+const targetPath = path.isAbsolute(targetArg)
+  ? targetArg
+  : path.resolve(envDir, targetArg);
+
+function exitWithMessage(message, code = 1) {
+  console.error(message);
+  process.exit(code);
+}
+
+if (!fs.existsSync(envDir)) {
+  exitWithMessage(`Target directory does not exist: ${envDir}`);
+}
+
+if (!fs.existsSync(templatePath)) {
+  exitWithMessage(`Missing template file: ${templatePath}`);
+}
+
+if (!forceOverwrite && fs.existsSync(targetPath)) {
+  const stats = fs.statSync(targetPath);
+  if (stats.size > 0) {
+    exitWithMessage(
+      `${targetPath} already exists and is not empty. Remove it manually or rerun with --force to overwrite.`,
+    );
+  }
+}
+
+const exampleContent = fs.readFileSync(templatePath, 'utf8');
+
+function generateSecret() {
+  return crypto.randomUUID({ disableEntropyCache: true }).replace(/-/g, '');
+}
+
+const apiKey = generateSecret();
+const adminPassword = generateSecret();
+
+const updatedContent = exampleContent
+  .replace(/^WAHA_API_KEY=.*/m, `WAHA_API_KEY=${apiKey}`)
+  .replace(/^WAHA_API_KEY_PLAIN=.*/m, `WAHA_API_KEY_PLAIN=${apiKey}`)
+  .replace(/^WAHA_DASHBOARD_USERNAME=.*/m, 'WAHA_DASHBOARD_USERNAME=admin')
+  .replace(
+    /^WAHA_DASHBOARD_PASSWORD=.*/m,
+    `WAHA_DASHBOARD_PASSWORD=${adminPassword}`,
+  )
+  .replace(/^WHATSAPP_SWAGGER_USERNAME=.*/m, 'WHATSAPP_SWAGGER_USERNAME=admin')
+  .replace(
+    /^WHATSAPP_SWAGGER_PASSWORD=.*/m,
+    `WHATSAPP_SWAGGER_PASSWORD=${adminPassword}`,
+  );
+
+fs.writeFileSync(targetPath, updatedContent, { encoding: 'utf8' });
+
+const generatedEnvValues = [
+  `WAHA_API_KEY=${apiKey}`,
+  `WAHA_API_KEY_PLAIN=${apiKey}`,
+  'WAHA_DASHBOARD_USERNAME=admin',
+  `WAHA_DASHBOARD_PASSWORD=${adminPassword}`,
+  'WHATSAPP_SWAGGER_USERNAME=admin',
+  `WHATSAPP_SWAGGER_PASSWORD=${adminPassword}`,
+];
+
+const lines = [
+  'Credentials generated.',
+  '',
+  'Generated env values:',
+  ...generatedEnvValues.map((line) => `  - ${line}`),
+  '',
+  'Use these credentials to login in Dashboard or Swagger:',
+  '  - Username: admin',
+  `  - Password: ${adminPassword}`,
+  '',
+  'Use this API key in the x-api-key header:',
+  `  - ${apiKey}`,
+  '',
+  'Read more:',
+  '  - https://waha.devlike.pro/docs/how-to/dashboard/#api-key',
+  '  - https://waha.devlike.pro/docs/how-to/security/',
+];
+
+console.log(lines.join('\n'));

scripts/release.js

@@ -0,0 +1,218 @@
+#!/usr/bin/env node
+'use strict';
+
+// eslint-disable-next-line @typescript-eslint/no-var-requires
+const { execFileSync } = require('child_process');
+// eslint-disable-next-line @typescript-eslint/no-var-requires
+const readline = require('readline');
+
+const DEV_BRANCH = process.env.WAHA_DEV_BRANCH || 'dev';
+const CORE_BRANCH = process.env.WAHA_CORE_BRANCH || 'core';
+const PLUS_BRANCH = process.env.WAHA_PLUS_BRANCH || 'plus';
+
+const CORE_PREFIX = '[core]';
+const PLUS_PREFIX = '[PLUS]';
+
+const args = process.argv.slice(2);
+const dryRun = args.includes('--dry-run');
+const assumeYes = args.includes('--yes') || args.includes('-y');
+
+function git(gitArgs, options) {
+  const opts = options || {};
+  return execFileSync('git', gitArgs, {
+    encoding: 'utf8',
+    stdio: opts.inherit ? 'inherit' : ['ignore', 'pipe', 'pipe'],
+  });
+}
+
+function gitOut(gitArgs) {
+  return git(gitArgs, { inherit: false }).trim();
+}
+
+function log(message) {
+  console.log(message);
+}
+
+function fail(message) {
+  console.error(`\n✗ ${message}`);
+  process.exit(1);
+}
+
+function ensureCleanTree() {
+  const status = gitOut(['status', '--porcelain']);
+  if (status) {
+    fail(
+      'Working tree is not clean. Commit or stash your changes before releasing.',
+    );
+  }
+}
+
+function ensureBranchExists(branch) {
+  try {
+    git(['rev-parse', '--verify', '--quiet', `refs/heads/${branch}`]);
+  } catch {
+    fail(`Branch "${branch}" does not exist locally.`);
+  }
+}
+
+// Non-merge commits in `boundary..head`, oldest first, whose subject starts
+// with prefix. The boundary is the last-released plus tip: dev is rebased onto
+// plus every release, so `plus..dev` is exactly the new, unreleased work.
+// We intentionally do not use `git cherry` (patch-id matching) because core is
+// a rewritten history whose old commits share no patch-ids with dev.
+function commitsToCherryPick(boundary, head, prefix) {
+  const format = '%H%x09%s';
+  const output = gitOut([
+    'rev-list',
+    '--reverse',
+    '--no-merges',
+    `--format=${format}`,
+    `${boundary}..${head}`,
+  ]);
+  if (!output) {
+    return [];
+  }
+  const picks = [];
+  for (const line of output.split('\n')) {
+    // rev-list --format prefixes each entry with a "commit <sha>" header line.
+    if (!line || line.startsWith('commit ')) {
+      continue;
+    }
+    const tab = line.indexOf('\t');
+    const sha = line.slice(0, tab);
+    const subject = line.slice(tab + 1);
+    if (subject.startsWith(prefix)) {
+      picks.push({ sha: sha, subject: subject });
+    }
+  }
+  return picks;
+}
+
+function cherryPickAll(picks) {
+  for (const pick of picks) {
+    log(`  cherry-pick ${pick.sha.slice(0, 9)} ${pick.subject}`);
+    if (dryRun) {
+      continue;
+    }
+    try {
+      git(['cherry-pick', pick.sha], { inherit: true });
+    } catch {
+      git(['cherry-pick', '--abort'], { inherit: true });
+      fail(
+        `Cherry-pick of ${pick.sha.slice(0, 9)} failed (conflict). ` +
+          `Aborted the cherry-pick — resolve manually and re-run.`,
+      );
+    }
+  }
+}
+
+function checkout(branch) {
+  log(`\n→ checkout ${branch}`);
+  if (!dryRun) {
+    git(['checkout', branch], { inherit: true });
+  }
+}
+
+function confirm(question) {
+  if (assumeYes || dryRun) {
+    return Promise.resolve(true);
+  }
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout,
+  });
+  return new Promise(function resolver(resolve) {
+    rl.question(`${question} [y/N] `, function onAnswer(answer) {
+      rl.close();
+      resolve(/^y(es)?$/i.test(answer.trim()));
+    });
+  });
+}
+
+async function main() {
+  ensureCleanTree();
+  [DEV_BRANCH, CORE_BRANCH, PLUS_BRANCH].forEach(ensureBranchExists);
+
+  const startBranch = gitOut(['rev-parse', '--abbrev-ref', 'HEAD']);
+
+  if (dryRun) {
+    log('Running in --dry-run mode: no branches will be modified.\n');
+  }
+
+  // Capture the last-released plus tip before we touch anything. Step 3 merges
+  // core into plus and moves the branch, so both pick sets must be computed
+  // against this saved boundary, not the live plus ref.
+  const boundary = gitOut(['rev-parse', PLUS_BRANCH]);
+  log(`Boundary (last released ${PLUS_BRANCH}): ${boundary.slice(0, 9)}\n`);
+
+  const corePicks = commitsToCherryPick(boundary, DEV_BRANCH, CORE_PREFIX);
+  log(
+    `Found ${corePicks.length} "${CORE_PREFIX}" commit(s) in ` +
+      `${DEV_BRANCH} since last ${PLUS_BRANCH} release.`,
+  );
+
+  // Step 1 + 2: bring missing [core] commits onto core.
+  checkout(CORE_BRANCH);
+  cherryPickAll(corePicks);
+
+  // Step 3: merge the freshly updated core into plus.
+  checkout(PLUS_BRANCH);
+  log(`\n→ merge ${CORE_BRANCH} into ${PLUS_BRANCH}`);
+  if (!dryRun) {
+    try {
+      git(['merge', '--no-edit', CORE_BRANCH], { inherit: true });
+    } catch {
+      git(['merge', '--abort'], { inherit: true });
+      fail(
+        `Merge of ${CORE_BRANCH} into ${PLUS_BRANCH} failed (conflict). ` +
+          `Aborted the merge — resolve manually and re-run.`,
+      );
+    }
+  }
+
+  // Step 4: bring missing [PLUS] commits onto plus (same saved boundary).
+  const plusPicks = commitsToCherryPick(boundary, DEV_BRANCH, PLUS_PREFIX);
+  log(
+    `\nFound ${plusPicks.length} "${PLUS_PREFIX}" commit(s) in ` +
+      `${DEV_BRANCH} since last ${PLUS_BRANCH} release.`,
+  );
+  cherryPickAll(plusPicks);
+
+  // Step 5: rebase dev onto the freshly built plus.
+  log(`\n→ rebase ${DEV_BRANCH} onto ${PLUS_BRANCH} (rewrites ${DEV_BRANCH})`);
+  const proceed = await confirm(
+    `This will force-rewrite "${DEV_BRANCH}". Continue?`,
+  );
+  if (!proceed) {
+    fail('Aborted before rebasing dev. core/plus changes are kept.');
+  }
+  checkout(DEV_BRANCH);
+  if (!dryRun) {
+    try {
+      git(['rebase', PLUS_BRANCH], { inherit: true });
+    } catch {
+      git(['rebase', '--abort'], { inherit: true });
+      fail(
+        `Rebase of ${DEV_BRANCH} onto ${PLUS_BRANCH} failed (conflict). ` +
+          `Aborted the rebase — resolve manually and re-run.`,
+      );
+    }
+  }
+
+  if (dryRun) {
+    checkout(startBranch);
+    log('\nDry run complete. Re-run without --dry-run to apply.');
+  } else {
+    log(
+      `\n✓ Release complete. ${DEV_BRANCH} now sits on top of ${PLUS_BRANCH}.`,
+    );
+    log(
+      `  Push when ready: git push origin ${CORE_BRANCH} ${PLUS_BRANCH} ` +
+        `&& git push --force-with-lease origin ${DEV_BRANCH}`,
+    );
+  }
+}
+
+main().catch(function onError(error) {
+  fail(error.message || String(error));
+});

scripts/up-dashboard.js

@@ -0,0 +1,34 @@
+#!/usr/bin/env node
+'use strict';
+
+// eslint-disable-next-line @typescript-eslint/no-var-requires
+const fs = require('fs');
+// eslint-disable-next-line @typescript-eslint/no-var-requires
+const { execSync } = require('child_process');
+
+const CONFIG_FILE = 'waha.config.json';
+
+const config = JSON.parse(fs.readFileSync(CONFIG_FILE, 'utf8'));
+const { repo } = config.waha.dashboard;
+if (!repo) {
+  console.error(`Missing dashboard.repo in ${CONFIG_FILE}`);
+  process.exit(1);
+}
+
+const branch = 'gh-pages';
+console.log(`Fetching latest commit for ${repo}@${branch}...`);
+
+const output = execSync(
+  `git ls-remote https://github.com/${repo} refs/heads/${branch}`,
+  { encoding: 'utf8' },
+);
+
+const sha = output.split('\t')[0].trim();
+if (!sha) {
+  console.error(`Could not resolve ref ${branch} for ${repo}`);
+  process.exit(1);
+}
+
+config.waha.dashboard.ref = sha;
+fs.writeFileSync(CONFIG_FILE, JSON.stringify(config, null, 2) + '\n', 'utf8');
+console.log(`Updated ${CONFIG_FILE}: dashboard.ref = ${sha}`);

scripts/waha-run.sh

@@ -1,23 +0,0 @@
-#!/bin/bash
-set -e
-echo "Starting WAHA..."
-
-docker run -d \
-    --restart=always \
-    --name waha \
-    -p 3000:3000/tcp \
-    -v ./.sessions:/app/.sessions \
-    -v ./.media:/app/.media \
-    --env WHATSAPP_API_KEY=321 \
-    --env WAHA_DASHBOARD_USERNAME=waha \
-    --env WAHA_DASHBOARD_PASSWORD=waha \
-    --env WAHA_LOG_FORMAT=PRETTY \
-    --env WAHA_LOG_LEVEL=info \
-    --env WHATSAPP_DEFAULT_ENGINE=WEBJS \
-    --env WHATSAPP_RESTART_ALL_SESSIONS=True \
-    --env WAHA_PRINT_QR=False \
-    --env WHATSAPP_FILES_LIFETIME=0 \
-    --env WHATSAPP_FILES_FOLDER=/app/.media \
-    devlikeapro/waha-plus:latest
-
-echo "WAHA started."

scripts/waha-update.sh

@@ -1,21 +0,0 @@
-set -e
-echo "Updating WAHA..."
-echo "Logging in to Docker..."
-docker login -u devlikeapro # -p {KEY} - you can hard code key here https://portal.devlike.pro/
-
-echo "Pulling the latest image..."
-docker pull devlikeapro/waha-plus
-
-echo "Logging out of Docker..."
-docker logout
-
-# Just pull if you're using WAHA Core
-# docker pull devlikeapro/waha
-
-echo "Stopping the current container..."
-docker stop waha || true
-echo "Removing the current container..."
-docker rm waha || true
-
-echo "Running WAHA..."
-sh ./waha-run.sh

src/__tests__/e2e/auth.test.ts

@@ -0,0 +1,391 @@
+import axios from 'axios';
+import WebSocket = require('ws');
+
+const VALID_API_KEY = '666';
+const VALID_USERNAME = 'admin';
+const VALID_PASSWORD = '666';
+const VALID_SESSION_API_KEY = 'key_0fQfI3n3rFVsczBbBfknLXKUreY2my6J';
+
+const BASE_URL = (process.env.WAHA_BASE_URL ?? 'http://localhost:3000').replace(
+  /\/$/,
+  '',
+);
+const WS_BASE_URL = BASE_URL.replace(/^http/, 'ws');
+
+const HTTP_OK = 200;
+const HTTP_CREATED = 201;
+const HTTP_UNAUTHORIZED = 401;
+const HTTP_FORBIDDEN = 403;
+const HTTP_NOT_FOUND = 404;
+const HTTP_UNPROCESSABLE = 422;
+const WS_POLICY_VIOLATION = 1008;
+const WS_OK_CODES = [1000, 1005];
+
+describe('admin - GET /api/sessions/{name}', () => {
+  test('no api key is unauthorized', async () => {
+    const response = await axios.get(`${BASE_URL}/api/sessions/default`, {
+      validateStatus: () => true,
+    });
+    expect(response.status).toBe(HTTP_UNAUTHORIZED);
+  });
+
+  test('valid api key is ok', async () => {
+    const response = await axios.get(`${BASE_URL}/api/sessions/default`, {
+      headers: { 'X-Api-Key': VALID_API_KEY },
+      validateStatus: () => true,
+    });
+    expect(response.status).toBe(HTTP_OK);
+  });
+
+  test('invalid api key is unauthorized', async () => {
+    const response = await axios.get(`${BASE_URL}/api/sessions/default`, {
+      headers: { 'X-Api-Key': '123' },
+      validateStatus: () => true,
+    });
+    expect(response.status).toBe(HTTP_UNAUTHORIZED);
+  });
+});
+
+describe('admin - POST /api/sessions', () => {
+  test('admin key can create a session without name and remove it', async () => {
+    const createResponse = await axios.post(
+      `${BASE_URL}/api/sessions`,
+      {},
+      {
+        headers: { 'X-Api-Key': VALID_API_KEY },
+        validateStatus: () => true,
+      },
+    );
+    expect(createResponse.status).toBe(HTTP_CREATED);
+    expect(createResponse.data?.name).toBeTruthy();
+
+    const deleteResponse = await axios.delete(
+      `${BASE_URL}/api/sessions/${createResponse.data.name}`,
+      {
+        headers: { 'X-Api-Key': VALID_API_KEY },
+        validateStatus: () => true,
+      },
+    );
+    expect(deleteResponse.status).toBe(HTTP_OK);
+  });
+});
+
+describe('GET /api/sessions?all=true', () => {
+  beforeAll(async () => {
+    const createResponse = await axios.post(
+      `${BASE_URL}/api/sessions`,
+      { name: 'another' },
+      {
+        headers: { 'X-Api-Key': VALID_API_KEY },
+        validateStatus: () => true,
+      },
+    );
+    if (![HTTP_CREATED, HTTP_UNPROCESSABLE].includes(createResponse.status)) {
+      throw new Error(
+        `Unexpected status for creating "another" session: ${createResponse.status}`,
+      );
+    }
+  });
+
+  afterAll(async () => {
+    const deleteResponse = await axios.delete(
+      `${BASE_URL}/api/sessions/another`,
+      {
+        headers: { 'X-Api-Key': VALID_API_KEY },
+        validateStatus: () => true,
+      },
+    );
+    if (![HTTP_OK, HTTP_NOT_FOUND].includes(deleteResponse.status)) {
+      throw new Error(
+        `Unexpected status for deleting "another" session: ${deleteResponse.status}`,
+      );
+    }
+  });
+
+  test('admin key returns two sessions', async () => {
+    const response = await axios.get(`${BASE_URL}/api/sessions?all=true`, {
+      headers: { 'X-Api-Key': VALID_API_KEY },
+      validateStatus: () => true,
+    });
+    expect(response.status).toBe(HTTP_OK);
+    expect(response.data).toHaveLength(2);
+    expect(response.data.map((session) => session.name).sort()).toEqual([
+      'another',
+      'default',
+    ]);
+  });
+
+  test('no api key is unauthorized', async () => {
+    const response = await axios.get(`${BASE_URL}/api/sessions?all=true`, {
+      validateStatus: () => true,
+    });
+    expect(response.status).toBe(HTTP_UNAUTHORIZED);
+  });
+
+  test('session key returns one session', async () => {
+    const response = await axios.get(`${BASE_URL}/api/sessions?all=true`, {
+      headers: { 'X-Api-Key': VALID_SESSION_API_KEY },
+      validateStatus: () => true,
+    });
+    expect(response.status).toBe(HTTP_OK);
+    expect(response.data).toHaveLength(1);
+    expect(response.data[0]?.name).toBe('default');
+  });
+});
+
+describe('GET /api/server/version', () => {
+  test('no api key is unauthorized', async () => {
+    const response = await axios.get(`${BASE_URL}/api/server/version`, {
+      validateStatus: () => true,
+    });
+    expect(response.status).toBe(HTTP_UNAUTHORIZED);
+  });
+
+  test('admin api key is ok', async () => {
+    const response = await axios.get(`${BASE_URL}/api/server/version`, {
+      headers: { 'X-Api-Key': VALID_API_KEY },
+      validateStatus: () => true,
+    });
+    expect(response.status).toBe(HTTP_OK);
+  });
+
+  test('session api key is ok', async () => {
+    const response = await axios.get(`${BASE_URL}/api/server/version`, {
+      headers: { 'X-Api-Key': VALID_SESSION_API_KEY },
+      validateStatus: () => true,
+    });
+    expect(response.status).toBe(HTTP_OK);
+  });
+});
+
+describe('GET /api/server/environment', () => {
+  test('no api key is unauthorized', async () => {
+    const response = await axios.get(`${BASE_URL}/api/server/environment`, {
+      validateStatus: () => true,
+    });
+    expect(response.status).toBe(HTTP_UNAUTHORIZED);
+  });
+
+  test('admin api key is ok', async () => {
+    const response = await axios.get(`${BASE_URL}/api/server/environment`, {
+      headers: { 'X-Api-Key': VALID_API_KEY },
+      validateStatus: () => true,
+    });
+    expect(response.status).toBe(HTTP_OK);
+  });
+
+  test('session api key is forbidden', async () => {
+    const response = await axios.get(`${BASE_URL}/api/server/environment`, {
+      headers: { 'X-Api-Key': VALID_SESSION_API_KEY },
+      validateStatus: () => true,
+    });
+    expect(response.status).toBe(HTTP_FORBIDDEN);
+  });
+});
+
+describe('admin - GET /health', () => {
+  test('no api key is unauthorized', async () => {
+    const response = await axios.get(`${BASE_URL}/health`, {
+      validateStatus: () => true,
+    });
+    expect(response.status).toBe(HTTP_UNAUTHORIZED);
+  });
+
+  test('valid api key is ok', async () => {
+    const response = await axios.get(`${BASE_URL}/health`, {
+      headers: { 'X-Api-Key': VALID_API_KEY },
+      validateStatus: () => true,
+    });
+    expect(response.status).toBe(HTTP_OK);
+  });
+
+  test('invalid api key is unauthorized', async () => {
+    const response = await axios.get(`${BASE_URL}/health`, {
+      headers: { 'X-Api-Key': '123' },
+      validateStatus: () => true,
+    });
+    expect(response.status).toBe(HTTP_UNAUTHORIZED);
+  });
+});
+
+describe('/ws', () => {
+  const buildWsUrl = (apiKey?: string) => {
+    const wsUrl = new URL('/ws', WS_BASE_URL);
+    wsUrl.searchParams.set('session', '*');
+    wsUrl.searchParams.set('events', '*');
+    if (apiKey) {
+      wsUrl.searchParams.set('x-api-key', apiKey);
+    }
+    return wsUrl.toString();
+  };
+
+  const waitForOpen = (socket: WebSocket, timeoutMs = 5_000) =>
+    new Promise<void>((resolve, reject) => {
+      const timeout = setTimeout(() => {
+        reject(new Error('WebSocket open timeout'));
+      }, timeoutMs);
+      socket.once('open', () => {
+        clearTimeout(timeout);
+        resolve();
+      });
+      socket.once('error', (error) => {
+        clearTimeout(timeout);
+        reject(error);
+      });
+    });
+
+  const waitForClose = (socket: WebSocket, timeoutMs = 5_000) =>
+    new Promise<{ code: number; reason: string }>((resolve, reject) => {
+      const timeout = setTimeout(() => {
+        reject(new Error('WebSocket close timeout'));
+      }, timeoutMs);
+      socket.once('close', (code, reason) => {
+        clearTimeout(timeout);
+        resolve({ code, reason: reason.toString() });
+      });
+      socket.once('error', (error) => {
+        clearTimeout(timeout);
+        reject(error);
+      });
+    });
+
+  test('no api key is unauthorized', async () => {
+    const socket = new WebSocket(buildWsUrl());
+    const { code } = await waitForClose(socket);
+    expect(code).toBe(WS_POLICY_VIOLATION);
+  });
+
+  test('admin api key is ok', async () => {
+    const socket = new WebSocket(buildWsUrl(VALID_API_KEY));
+    await waitForOpen(socket);
+    socket.close();
+    const { code } = await waitForClose(socket);
+    expect(WS_OK_CODES).toContain(code);
+  });
+});
+
+describe('GET /api/files/test.txt', () => {
+  // create "test.txt" in current dir/.media/test.txt
+  let file = null;
+  beforeAll(() => {
+    const fs = require('fs');
+    const path = require('path');
+    const mediaDir = path.resolve('./.media');
+    if (!fs.existsSync(mediaDir)) {
+      fs.mkdirSync(mediaDir);
+    }
+    const filePath = path.join(mediaDir, 'test.txt');
+    fs.writeFileSync(filePath, 'This is a test file.');
+    file = filePath;
+  });
+  test('no api key is unauthorized', async () => {
+    const response = await axios.get(`${BASE_URL}/api/files/test.txt`, {
+      validateStatus: () => true,
+    });
+    expect(response.status).toBe(HTTP_UNAUTHORIZED);
+  });
+
+  test('valid api key is ok', async () => {
+    const response = await axios.get(`${BASE_URL}/api/files/test.txt`, {
+      headers: { 'X-Api-Key': VALID_API_KEY },
+      validateStatus: () => true,
+    });
+    expect(response.status).toBe(HTTP_OK);
+  });
+
+  test('invalid api key is unauthorized', async () => {
+    const response = await axios.get(`${BASE_URL}/api/files/test.txt`, {
+      headers: { 'X-Api-Key': '123' },
+      validateStatus: () => true,
+    });
+    expect(response.status).toBe(HTTP_UNAUTHORIZED);
+  });
+});
+
+describe('GET /', () => {
+  test('no auth is unauthorized', async () => {
+    const response = await axios.get(`${BASE_URL}/`, {
+      validateStatus: () => true,
+    });
+    expect(response.status).toBe(HTTP_UNAUTHORIZED);
+  });
+
+  test('valid auth is ok', async () => {
+    const response = await axios.get(`${BASE_URL}/`, {
+      auth: { username: VALID_USERNAME, password: VALID_PASSWORD },
+      validateStatus: () => true,
+    });
+    expect(response.status).toBe(HTTP_OK);
+  });
+
+  test('wrong auth is unauthorized', async () => {
+    const response = await axios.get(`${BASE_URL}/`, {
+      auth: { username: VALID_USERNAME, password: 'password-another' },
+      validateStatus: () => true,
+    });
+    expect(response.status).toBe(HTTP_UNAUTHORIZED);
+  });
+});
+
+describe('GET /dashboard', () => {
+  test('no auth is unauthorized', async () => {
+    const response = await axios.get(`${BASE_URL}/dashboard/`, {
+      validateStatus: () => true,
+    });
+    expect(response.status).toBe(HTTP_UNAUTHORIZED);
+  });
+
+  test('valid auth is ok', async () => {
+    const response = await axios.get(`${BASE_URL}/dashboard/`, {
+      auth: { username: VALID_USERNAME, password: VALID_PASSWORD },
+      validateStatus: () => true,
+    });
+    expect(response.status).toBe(HTTP_OK);
+  });
+
+  test('wrong auth is unauthorized', async () => {
+    const response = await axios.get(`${BASE_URL}/dashboard/`, {
+      auth: { username: VALID_USERNAME, password: 'password-another' },
+      validateStatus: () => true,
+    });
+    expect(response.status).toBe(HTTP_UNAUTHORIZED);
+  });
+});
+
+describe('session key - GET /api/sessions/{name}', () => {
+  test('default key - default session - is authorized', async () => {
+    const response = await axios.get(`${BASE_URL}/api/sessions/default`, {
+      headers: { 'X-Api-Key': VALID_SESSION_API_KEY },
+      validateStatus: () => true,
+    });
+    expect(response.status).toBe(HTTP_OK);
+  });
+
+  test('default key - create a new sessions - forbidden', async () => {
+    const response = await axios.post(
+      `${BASE_URL}/api/sessions`,
+      { name: 'newone' },
+      {
+        headers: { 'X-Api-Key': VALID_SESSION_API_KEY },
+        validateStatus: () => true,
+      },
+    );
+    expect(response.status).toBe(HTTP_FORBIDDEN);
+  });
+
+  test('another key - default session - unauthorized', async () => {
+    const response = await axios.get(`${BASE_URL}/api/sessions/default`, {
+      headers: { 'X-Api-Key': 'key_another' },
+      validateStatus: () => true,
+    });
+    expect(response.status).toBe(HTTP_UNAUTHORIZED);
+  });
+
+  test('default key - another session - forbidden', async () => {
+    const response = await axios.get(`${BASE_URL}/api/sessions/another`, {
+      headers: { 'X-Api-Key': VALID_SESSION_API_KEY },
+      validateStatus: () => true,
+    });
+    expect(response.status).toBe(HTTP_FORBIDDEN);
+  });
+});

src/api/apikeys.controller.ts

@@ -0,0 +1,86 @@
+import {
+  Body,
+  Controller,
+  Delete,
+  Get,
+  Param,
+  Post,
+  Put,
+  UseGuards,
+  UsePipes,
+} from '@nestjs/common';
+import { ApiOperation, ApiSecurity, ApiTags } from '@nestjs/swagger';
+import { SessionManager } from '@waha/core/abc/manager.abc';
+import { Action } from '@waha/core/auth/casl.types';
+import { CanServer, CanSession, FromBody } from '@waha/core/auth/policies';
+import { CheckPolicies } from '@waha/core/auth/policies.decorator';
+import { PoliciesGuard } from '@waha/core/auth/policies.guard';
+import { ApiKeyService } from '@waha/core/services/ApiKeyService';
+import { WAHAValidationPipe } from '@waha/nestjs/pipes/WAHAValidationPipe';
+import {
+  ApiKeyDTO,
+  ApiKeyRequest,
+  ScopedApiKeyRequest,
+} from '@waha/structures/apikeys.dto';
+
+@ApiSecurity('api_key')
+@Controller('api/keys')
+@ApiTags('🔑 Api Keys')
+@UseGuards(PoliciesGuard)
+@CheckPolicies(CanServer(Action.Manage))
+export class ApiKeysController {
+  constructor(private manager: SessionManager) {}
+
+  private get service(): ApiKeyService {
+    return new ApiKeyService(this.manager);
+  }
+
+  @Post('/')
+  @ApiOperation({ summary: 'Create a new API key' })
+  @UsePipes(new WAHAValidationPipe())
+  async create(@Body() body: ApiKeyRequest): Promise<ApiKeyDTO> {
+    return this.service.create(body);
+  }
+
+  @Get('/')
+  @ApiOperation({ summary: 'Get all API keys' })
+  async list(): Promise<ApiKeyDTO[]> {
+    return this.service.list();
+  }
+
+  @Post('/media')
+  @ApiOperation({
+    summary: 'Create or get a media-download-only API key for a session',
+  })
+  @CheckPolicies(CanSession(Action.Read, FromBody('session')))
+  @UsePipes(new WAHAValidationPipe())
+  async media(@Body() body: ScopedApiKeyRequest): Promise<ApiKeyDTO> {
+    return this.service.createOrGetMediaKey(body.session);
+  }
+
+  @Post('/control')
+  @ApiOperation({
+    summary: 'Create or get a control-only API key for a session',
+  })
+  @CheckPolicies(CanSession(Action.Control, FromBody('session')))
+  @UsePipes(new WAHAValidationPipe())
+  async control(@Body() body: ScopedApiKeyRequest): Promise<ApiKeyDTO> {
+    return this.service.createOrGetControlKey(body.session);
+  }
+
+  @Put('/:id')
+  @ApiOperation({ summary: 'Update an API key' })
+  @UsePipes(new WAHAValidationPipe())
+  async update(
+    @Param('id') id: string,
+    @Body() body: ApiKeyRequest,
+  ): Promise<ApiKeyDTO> {
+    return this.service.update(id, body);
+  }
+
+  @Delete('/:id')
+  @ApiOperation({ summary: 'Delete an API key' })
+  async delete(@Param('id') id: string): Promise<{ result: true }> {
+    return this.service.delete(id);
+  }
+}

src/api/auth.controller.ts

@@ -5,46 +5,59 @@ import {
   Post,
   Query,
   UseInterceptors,
+  UseGuards,
 } from '@nestjs/common';
-import { UnprocessableEntityException } from '@nestjs/common/exceptions/unprocessable-entity.exception';
-import { ApiOperation, ApiSecurity, ApiTags } from '@nestjs/swagger';
+import {
+  ApiOkResponse,
+  ApiOperation,
+  ApiSecurity,
+  ApiTags,
+} from '@nestjs/swagger';
+import { ApiFileAcceptHeader } from '@waha/nestjs/ApiFileAcceptHeader';
+import {
+  QRCodeSessionParam,
+  SessionApiParam,
+  SessionParam,
+} from '@waha/nestjs/params/SessionApiParam';
 
 import { SessionManager } from '../core/abc/manager.abc';
 import { WhatsappSession } from '../core/abc/session.abc';
+import { BufferResponseInterceptor } from '../nestjs/BufferResponseInterceptor';
 import {
-  CaptchaBody,
-  OTPRequest,
+  PasskeyAssertionRequest,
+  PasskeyChallenge,
+  PasskeyConfirmationResponse,
   QRCodeFormat,
   QRCodeQuery,
   QRCodeValue,
   RequestCodeRequest,
 } from '../structures/auth.dto';
-import { WAHASessionStatus } from '../structures/enums.dto';
 import { Base64File } from '../structures/files.dto';
-import { BufferResponseInterceptor } from './BufferResponseInterceptor';
-import { ApiFileAcceptHeader, SessionApiParam, SessionParam } from './helpers';
+import { PoliciesGuard } from '@waha/core/auth/policies.guard';
+import { CheckPolicies } from '@waha/core/auth/policies.decorator';
+import { CanSession, FromParam } from '@waha/core/auth/policies';
+
+import { Action } from '@waha/core/auth/casl.types';
 
 @ApiSecurity('api_key')
 @Controller('api/:session/auth')
-@ApiTags('auth')
+@ApiTags('📱 Pairing')
+@UseGuards(PoliciesGuard)
+@CheckPolicies(CanSession(Action.Control, FromParam('session')))
 class AuthController {
   constructor(private manager: SessionManager) {}
 
   @Get('qr')
   @ApiOperation({
-    summary: 'Get QR code for pairing WhatsApp Web.',
+    summary: 'Get QR code for pairing WhatsApp API.',
   })
   @SessionApiParam
-  @ApiFileAcceptHeader(Base64File, QRCodeValue)
-  @UseInterceptors(new BufferResponseInterceptor())
+  @ApiFileAcceptHeader('image/png', Base64File, QRCodeValue)
+  @UseInterceptors(new BufferResponseInterceptor('image/png'))
   async getQR(
-    @SessionParam session: WhatsappSession,
+    @QRCodeSessionParam session: WhatsappSession,
     @Query() query: QRCodeQuery,
   ): Promise<Buffer | QRCodeValue> {
-    if (session.status != WAHASessionStatus.SCAN_QR_CODE) {
-      const err = `Can get QR code only in SCAN_QR_CODE status. The current status is '${session.status}'`;
-      throw new UnprocessableEntityException(err);
-    }
     const qr = session.getQR();
     if (query.format == QRCodeFormat.RAW) {
       return { value: qr.raw };
@@ -64,40 +77,52 @@ class AuthController {
     return session.requestCode(request.phoneNumber, request.method, request);
   }
 
-  @Post('authorize-code')
+  @Get('passkey/challenge')
   @SessionApiParam
   @ApiOperation({
-    summary: 'Send OTP authentication code.',
+    summary: 'Get the pending passkey (WebAuthn) challenge.',
+    description:
+      'Available while the session is in PASSKEY_REQUIRED status. ' +
+      'Pass the challenge to navigator.credentials.get({ publicKey: challenge }) ' +
+      'on the https://web.whatsapp.com origin.',
   })
-  authorizeCode(
-    @SessionParam session: WhatsappSession,
-    @Body() request: OTPRequest,
-  ) {
-    return session.authorizeCode(request.code);
+  @ApiOkResponse({ type: PasskeyChallenge })
+  getPasskeyChallenge(@SessionParam session: WhatsappSession) {
+    return session.getPasskeyChallenge();
   }
 
-  @Get('captcha')
+  @Post('passkey')
   @SessionApiParam
-  @ApiFileAcceptHeader()
-  @UseInterceptors(new BufferResponseInterceptor())
   @ApiOperation({
-    summary: 'Get captcha image.',
+    summary: 'Submit a WebAuthn passkey assertion to finish pairing.',
   })
-  async getCaptcha(@SessionParam session: WhatsappSession): Promise<Buffer> {
-    const image = await session.getCaptcha();
-    return image.get();
+  submitPasskey(
+    @SessionParam session: WhatsappSession,
+    @Body() request: PasskeyAssertionRequest,
+  ) {
+    return session.sendPasskeyResponse(JSON.stringify(request));
   }
 
-  @Post('captcha')
+  @Get('passkey/confirmation')
   @SessionApiParam
   @ApiOperation({
-    summary: 'Enter captcha code.',
+    summary: 'Get the pending passkey confirmation code.',
+    description:
+      'Available while the session is in PASSKEY_CONFIRMATION_REQUIRED status. ' +
+      'Most pairings skip this step - WhatsApp confirms them right after the assertion.',
   })
-  saveCaptcha(
-    @SessionParam session: WhatsappSession,
-    @Body() body: CaptchaBody,
-  ) {
-    return session.saveCaptcha(body.code);
+  @ApiOkResponse({ type: PasskeyConfirmationResponse })
+  getPasskeyConfirmation(@SessionParam session: WhatsappSession) {
+    return session.getPasskeyConfirmation();
+  }
+
+  @Post('passkey/confirm')
+  @SessionApiParam
+  @ApiOperation({
+    summary: 'Confirm passkey pairing (only needed for the manual code case).',
+  })
+  confirmPasskey(@SessionParam session: WhatsappSession) {
+    return session.confirmPasskey();
   }
 }
 

src/api/calls.controller.ts

@@ -0,0 +1,42 @@
+import {
+  Body,
+  Controller,
+  Post,
+  UseGuards,
+  UsePipes,
+  ValidationPipe,
+} from '@nestjs/common';
+import { ApiOperation, ApiSecurity, ApiTags } from '@nestjs/swagger';
+import {
+  SessionApiParam,
+  WorkingSessionParam,
+} from '@waha/nestjs/params/SessionApiParam';
+
+import { SessionManager } from '../core/abc/manager.abc';
+import { WhatsappSession } from '../core/abc/session.abc';
+import { RejectCallRequest } from '../structures/calls.dto';
+import { PoliciesGuard } from '@waha/core/auth/policies.guard';
+import { CheckPolicies } from '@waha/core/auth/policies.decorator';
+import { CanSession, FromParam } from '@waha/core/auth/policies';
+
+import { Action } from '@waha/core/auth/casl.types';
+
+@ApiSecurity('api_key')
+@Controller('api/:session/calls')
+@ApiTags('📞 Calls')
+@UseGuards(PoliciesGuard)
+@CheckPolicies(CanSession(Action.Send, FromParam('session')))
+export class CallsController {
+  constructor(private manager: SessionManager) {}
+
+  @Post('reject')
+  @SessionApiParam
+  @ApiOperation({ summary: 'Reject incoming call' })
+  @UsePipes(new ValidationPipe({ transform: true, whitelist: true }))
+  rejectCall(
+    @WorkingSessionParam session: WhatsappSession,
+    @Body() request: RejectCallRequest,
+  ) {
+    return session.rejectCall(request.from, request.id);
+  }
+}

src/api/channels.controller.ts

@@ -3,34 +3,65 @@ import {
   Controller,
   Delete,
   Get,
+  HttpCode,
+  HttpStatus,
   Param,
   Post,
   Query,
+  UseGuards,
+  UsePipes,
 } from '@nestjs/common';
-import { ApiOperation, ApiSecurity, ApiTags } from '@nestjs/swagger';
+import { ApiOperation, ApiParam, ApiSecurity, ApiTags } from '@nestjs/swagger';
+import { ChannelsInfoServiceCore } from '@waha/core/services/ChannelsInfoServiceCore';
+import { isJidNewsletter } from '@waha/core/utils/jids';
+import {
+  SessionApiParam,
+  WorkingSessionParam,
+} from '@waha/nestjs/params/SessionApiParam';
+import { WAHAValidationPipe } from '@waha/nestjs/pipes/WAHAValidationPipe';
 import {
   Channel,
+  ChannelCategory,
+  ChannelCountry,
+  ChannelListResult,
+  ChannelMessage,
+  ChannelSearchByText,
+  ChannelSearchByView,
+  ChannelView,
   CreateChannelRequest,
   ListChannelsQuery,
   NewsletterIdApiParam,
   NewsletterIdOrInviteCodeApiParam,
+  PreviewChannelMessages,
 } from '@waha/structures/channels.dto';
 
 import { SessionManager } from '../core/abc/manager.abc';
-import { isNewsletter, WhatsappSession } from '../core/abc/session.abc';
-import { SessionApiParam, SessionParam } from './helpers';
+import {
+  parseChannelInviteLink,
+  WhatsappSession,
+} from '../core/abc/session.abc';
+import { PoliciesGuard } from '@waha/core/auth/policies.guard';
+import { CheckPolicies } from '@waha/core/auth/policies.decorator';
+import { CanSession, FromParam } from '@waha/core/auth/policies';
+
+import { Action } from '@waha/core/auth/casl.types';
 
 @ApiSecurity('api_key')
 @Controller('api/:session/channels')
-@ApiTags('channels')
+@ApiTags('📢 Channels')
+@UseGuards(PoliciesGuard)
 export class ChannelsController {
-  constructor(private manager: SessionManager) {}
+  constructor(
+    private manager: SessionManager,
+    private channelsInfoService: ChannelsInfoServiceCore,
+  ) {}
 
   @Get('')
   @SessionApiParam
+  @CheckPolicies(CanSession(Action.Read, FromParam('session')))
   @ApiOperation({ summary: 'Get list of know channels' })
   async list(
-    @SessionParam session: WhatsappSession,
+    @WorkingSessionParam session: WhatsappSession,
     @Query() query: ListChannelsQuery,
   ): Promise<Channel[]> {
     return session.channelsList(query);
@@ -38,9 +69,10 @@ export class ChannelsController {
 
   @Post('')
   @SessionApiParam
+  @CheckPolicies(CanSession(Action.Send, FromParam('session')))
   @ApiOperation({ summary: 'Create a new channel.' })
   create(
-    @SessionParam session: WhatsappSession,
+    @WorkingSessionParam session: WhatsappSession,
     @Body() request: CreateChannelRequest,
   ): Promise<Channel> {
     return session.channelsCreateChannel(request);
@@ -49,71 +81,167 @@ export class ChannelsController {
   @Delete(':id')
   @SessionApiParam
   @NewsletterIdApiParam
+  @CheckPolicies(CanSession(Action.Send, FromParam('session')))
   @ApiOperation({ summary: 'Delete the channel.' })
-  delete(@SessionParam session: WhatsappSession, @Param('id') id: string) {
+  delete(
+    @WorkingSessionParam session: WhatsappSession,
+    @Param('id') id: string,
+  ) {
     return session.channelsDeleteChannel(id);
   }
 
   @Get(':id')
   @SessionApiParam
   @NewsletterIdOrInviteCodeApiParam
+  @CheckPolicies(CanSession(Action.Read, FromParam('session')))
   @ApiOperation({
-    summary: 'Get the channel info - either by id @newsletter OR invite code.',
+    summary: 'Get the channel info',
+    description:
+      'You can use either id (123@newsletter) ' +
+      'OR invite code (https://www.whatsapp.com/channel/123)',
   })
   get(
-    @SessionParam session: WhatsappSession,
+    @WorkingSessionParam session: WhatsappSession,
     @Param('id') id: string,
   ): Promise<Channel> {
-    if (isNewsletter(id)) {
+    if (isJidNewsletter(id)) {
       return session.channelsGetChannel(id);
     } else {
-      // https://www.whatsapp.com/channel/123 => 123
-      const inviteCode = id.split('/').pop();
+      const inviteCode = parseChannelInviteLink(id);
       return session.channelsGetChannelByInviteCode(inviteCode);
     }
   }
 
-  @Post('follow')
+  @Get(':id/messages/preview')
+  @SessionApiParam
+  @CheckPolicies(CanSession(Action.Read, FromParam('session')))
+  @UsePipes(new WAHAValidationPipe())
+  @ApiParam({
+    name: 'id',
+    description: 'Channel id or invite code',
+    required: true,
+    type: 'string',
+    schema: {
+      default: '0029Va4K0PZ5a245NkngBA2M',
+    },
+  })
+  @ApiOperation({
+    summary: 'Preview channel messages',
+    description:
+      'You can use either ' +
+      'invite code (https://www.whatsapp.com/channel/123) or (123)' +
+      'OR' +
+      'Channel ID (123@newsletter).',
+  })
+  async previewChannelMessages(
+    @WorkingSessionParam session: WhatsappSession,
+    @Param('id') codeOrId: string,
+    @Query() query: PreviewChannelMessages,
+  ): Promise<ChannelMessage[]> {
+    let code = null;
+    if (isJidNewsletter(codeOrId)) {
+      const channel = await session.channelsGetChannel(codeOrId);
+      code = parseChannelInviteLink(channel.invite);
+    }
+    const inviteCode = parseChannelInviteLink(code || codeOrId);
+    return session.previewChannelMessages(inviteCode, query);
+  }
+
+  @Post(':id/follow')
   @SessionApiParam
   @NewsletterIdApiParam
+  @CheckPolicies(CanSession(Action.Send, FromParam('session')))
   @ApiOperation({ summary: 'Follow the channel.' })
   follow(
-    @SessionParam session: WhatsappSession,
+    @WorkingSessionParam session: WhatsappSession,
     @Param('id') id: string,
   ): Promise<void> {
     return session.channelsFollowChannel(id);
   }
 
-  @Post('unfollow')
+  @Post(':id/unfollow')
   @SessionApiParam
   @NewsletterIdApiParam
+  @CheckPolicies(CanSession(Action.Send, FromParam('session')))
   @ApiOperation({ summary: 'Unfollow the channel.' })
   unfollow(
-    @SessionParam session: WhatsappSession,
+    @WorkingSessionParam session: WhatsappSession,
     @Param('id') id: string,
   ): Promise<void> {
     return session.channelsUnfollowChannel(id);
   }
 
-  @Post('mute')
+  @Post(':id/mute')
   @SessionApiParam
   @NewsletterIdApiParam
+  @CheckPolicies(CanSession(Action.Send, FromParam('session')))
   @ApiOperation({ summary: 'Mute the channel.' })
   mute(
-    @SessionParam session: WhatsappSession,
+    @WorkingSessionParam session: WhatsappSession,
     @Param('id') id: string,
   ): Promise<void> {
     return session.channelsMuteChannel(id);
   }
 
-  @Post('unmute')
+  @Post(':id/unmute')
   @SessionApiParam
   @NewsletterIdApiParam
+  @CheckPolicies(CanSession(Action.Send, FromParam('session')))
   @ApiOperation({ summary: 'Unmute the channel.' })
   unmute(
-    @SessionParam session: WhatsappSession,
+    @WorkingSessionParam session: WhatsappSession,
     @Param('id') id: string,
   ): Promise<void> {
     return session.channelsUnmuteChannel(id);
   }
+
+  @Post('/search/by-view')
+  @HttpCode(HttpStatus.OK)
+  @SessionApiParam
+  @CheckPolicies(CanSession(Action.Read, FromParam('session')))
+  @UsePipes(new WAHAValidationPipe())
+  @ApiOperation({ summary: 'Search for channels (by view)' })
+  async searchByView(
+    @WorkingSessionParam session: WhatsappSession,
+    @Body() request: ChannelSearchByView,
+  ): Promise<ChannelListResult> {
+    return session.searchChannelsByView(request);
+  }
+
+  @Post('/search/by-text')
+  @HttpCode(HttpStatus.OK)
+  @SessionApiParam
+  @CheckPolicies(CanSession(Action.Read, FromParam('session')))
+  @UsePipes(new WAHAValidationPipe())
+  @ApiOperation({ summary: 'Search for channels (by text)' })
+  async searchByText(
+    @WorkingSessionParam session: WhatsappSession,
+    @Body() request: ChannelSearchByText,
+  ): Promise<ChannelListResult> {
+    return session.searchChannelsByText(request);
+  }
+
+  @Get('/search/views')
+  @SessionApiParam
+  @CheckPolicies(CanSession(Action.Read, FromParam('session')))
+  @ApiOperation({ summary: 'Get list of views for channel search' })
+  getSearchViews(): Promise<ChannelView[]> {
+    return this.channelsInfoService.getViews();
+  }
+
+  @Get('/search/countries')
+  @SessionApiParam
+  @CheckPolicies(CanSession(Action.Read, FromParam('session')))
+  @ApiOperation({ summary: 'Get list of countries for channel search' })
+  getSearchCountries(): Promise<ChannelCountry[]> {
+    return this.channelsInfoService.getCountries();
+  }
+
+  @Get('/search/categories')
+  @SessionApiParam
+  @CheckPolicies(CanSession(Action.Read, FromParam('session')))
+  @ApiOperation({ summary: 'Get list of categories for channel search' })
+  getSearchCategories(): Promise<ChannelCategory[]> {
+    return this.channelsInfoService.getCategories();
+  }
 }

src/api/chats.controller.ts

@@ -3,71 +3,215 @@ import {
   Controller,
   Delete,
   Get,
+  NotFoundException,
   Param,
   Post,
   Put,
   Query,
+  UseGuards,
   UsePipes,
   ValidationPipe,
 } from '@nestjs/common';
 import { ApiOperation, ApiSecurity, ApiTags } from '@nestjs/swagger';
+import { ChatIdApiParam } from '@waha/nestjs/params/ChatIdApiParam';
+import { MessageIdApiParam } from '@waha/nestjs/params/MessageIdApiParam';
+import {
+  SessionApiParam,
+  WorkingSessionParam,
+} from '@waha/nestjs/params/SessionApiParam';
 
 import { SessionManager } from '../core/abc/manager.abc';
 import { WhatsappSession } from '../core/abc/session.abc';
-import { parseBool } from '../helpers';
-import { GetChatMessagesQuery, GetChatsQuery } from '../structures/chats.dto';
-import { EditMessageRequest } from '../structures/chatting.dto';
 import {
-  ChatIdApiParam,
-  MessageIdApiParam,
-  SessionApiParam,
-  SessionParam,
-} from './helpers';
+  ChatPictureQuery,
+  ChatPictureResponse,
+  ChatSummary,
+  GetChatMessageQuery,
+  GetChatMessagesFilter,
+  GetChatMessagesQuery,
+  GetChatsOverviewParams,
+  GetChatsParams,
+  MessageSortField,
+  OverviewBodyRequest,
+  OverviewFilter,
+  PinMessageRequest,
+  ReadChatMessagesQuery,
+  ReadChatMessagesResponse,
+  transformAck,
+} from '../structures/chats.dto';
+import { EditMessageRequest } from '../structures/chatting.dto';
+import { SortOrder } from '@waha/structures/pagination.dto';
+import { PoliciesGuard } from '@waha/core/auth/policies.guard';
+import { CheckPolicies } from '@waha/core/auth/policies.decorator';
+import { CanSession, FromParam } from '@waha/core/auth/policies';
+
+import { Action } from '@waha/core/auth/casl.types';
 
 @ApiSecurity('api_key')
 @Controller('api/:session/chats')
-@ApiTags('chats')
+@ApiTags('💬 Chats')
 @UsePipes(new ValidationPipe({ transform: true }))
+@UseGuards(PoliciesGuard)
 class ChatsController {
   constructor(private manager: SessionManager) {}
 
   @Get('')
   @SessionApiParam
+  @CheckPolicies(CanSession(Action.Read, FromParam('session')))
   @ApiOperation({ summary: 'Get chats' })
   getChats(
-    @SessionParam session: WhatsappSession,
-    @Query() query: GetChatsQuery,
+    @WorkingSessionParam session: WhatsappSession,
+    @Query() pagination: GetChatsParams,
   ) {
-    return session.getChats(query);
+    return session.getChats(pagination);
+  }
+
+  @Get('overview')
+  @SessionApiParam
+  @CheckPolicies(CanSession(Action.Read, FromParam('session')))
+  @ApiOperation({
+    summary:
+      'Get chats overview. Includes all necessary things to build UI "your chats overview" page - chat id, name, picture, last message. Sorting by last message timestamp',
+  })
+  @UsePipes(new ValidationPipe({ transform: true, whitelist: true }))
+  getChatsOverview(
+    @WorkingSessionParam session: WhatsappSession,
+    @Query() pagination: GetChatsOverviewParams,
+    @Query() filter: OverviewFilter,
+  ): Promise<ChatSummary[]> {
+    return session.getChatsOverview(pagination, filter);
+  }
+
+  @Post('overview')
+  @SessionApiParam
+  @CheckPolicies(CanSession(Action.Read, FromParam('session')))
+  @ApiOperation({
+    summary:
+      'Get chats overview. Use POST if you have too many "ids" params - GET can limit it',
+  })
+  @UsePipes(new ValidationPipe({ transform: true, whitelist: true }))
+  postChatsOverview(
+    @WorkingSessionParam session: WhatsappSession,
+    @Body() body: OverviewBodyRequest,
+  ): Promise<ChatSummary[]> {
+    return session.getChatsOverview(body.pagination, body.filter);
   }
 
   @Delete(':chatId')
   @SessionApiParam
+  @CheckPolicies(CanSession(Action.Send, FromParam('session')))
   @ApiOperation({ summary: 'Deletes the chat' })
+  @ChatIdApiParam
   deleteChat(
-    @SessionParam session: WhatsappSession,
+    @WorkingSessionParam session: WhatsappSession,
     @Param('chatId') chatId: string,
   ) {
     return session.deleteChat(chatId);
   }
 
+  @Get(':chatId/picture')
+  @SessionApiParam
+  @CheckPolicies(CanSession(Action.Read, FromParam('session')))
+  @ApiOperation({ summary: 'Gets chat picture' })
+  @UsePipes(new ValidationPipe({ transform: true, whitelist: true }))
+  async getChatPicture(
+    @WorkingSessionParam session: WhatsappSession,
+    @Param('chatId') chatId: string,
+    @Query() query: ChatPictureQuery,
+  ): Promise<ChatPictureResponse> {
+    const url = await session.getContactProfilePicture(chatId, query.refresh);
+    return { url: url };
+  }
+
   @Get(':chatId/messages')
   @SessionApiParam
+  @CheckPolicies(CanSession(Action.Read, FromParam('session')))
   @ApiOperation({ summary: 'Gets messages in the chat' })
+  @ChatIdApiParam
+  @UsePipes(new ValidationPipe({ transform: true, whitelist: true }))
   getChatMessages(
     @Query() query: GetChatMessagesQuery,
-    @SessionParam session: WhatsappSession,
+    @Query() filter: GetChatMessagesFilter,
+    @WorkingSessionParam session: WhatsappSession,
     @Param('chatId') chatId: string,
   ) {
-    const downloadMedia = parseBool(query.downloadMedia);
-    return session.getChatMessages(chatId, query.limit, downloadMedia);
+    if (query.sortBy == MessageSortField.MESSAGE_TIMESTAMP) {
+      query.sortBy = MessageSortField.TIMESTAMP;
+    }
+    query.sortBy = query.sortBy || MessageSortField.TIMESTAMP;
+    query.sortOrder = query.sortOrder || SortOrder.DESC;
+    filter = transformAck(filter);
+    return session.getChatMessages(chatId, query, filter);
+  }
+
+  @Post(':chatId/messages/read')
+  @SessionApiParam
+  @CheckPolicies(CanSession(Action.Send, FromParam('session')))
+  @ApiOperation({ summary: 'Read unread messages in the chat' })
+  @ChatIdApiParam
+  @UsePipes(new ValidationPipe({ transform: true, whitelist: true }))
+  readChatMessages(
+    @Query() query: ReadChatMessagesQuery,
+    @WorkingSessionParam session: WhatsappSession,
+    @Param('chatId') chatId: string,
+  ): Promise<ReadChatMessagesResponse> {
+    return session.readChatMessages(chatId, query);
+  }
+
+  @Get(':chatId/messages/:messageId')
+  @SessionApiParam
+  @CheckPolicies(CanSession(Action.Read, FromParam('session')))
+  @ApiOperation({ summary: 'Gets message by id' })
+  @ChatIdApiParam
+  async getChatMessage(
+    @Query() query: GetChatMessageQuery,
+    @WorkingSessionParam session: WhatsappSession,
+    @Param('chatId') chatId: string,
+    @Param('messageId') messageId: string,
+  ) {
+    const message = await session.getChatMessage(chatId, messageId, query);
+    if (!message) {
+      throw new NotFoundException('Message not found');
+    }
+    return message;
+  }
+
+  @Post(':chatId/messages/:messageId/pin')
+  @SessionApiParam
+  @CheckPolicies(CanSession(Action.Send, FromParam('session')))
+  @ApiOperation({ summary: 'Pins a message in the chat' })
+  @ChatIdApiParam
+  async pinMessage(
+    @WorkingSessionParam session: WhatsappSession,
+    @Param('chatId') chatId: string,
+    @Param('messageId') messageId: string,
+    @Body() body: PinMessageRequest,
+  ) {
+    const result = await session.pinMessage(chatId, messageId, body.duration);
+    return { success: result };
+  }
+
+  @Post(':chatId/messages/:messageId/unpin')
+  @SessionApiParam
+  @CheckPolicies(CanSession(Action.Send, FromParam('session')))
+  @ApiOperation({ summary: 'Unpins a message in the chat' })
+  @ChatIdApiParam
+  async unpinMessage(
+    @WorkingSessionParam session: WhatsappSession,
+    @Param('chatId') chatId: string,
+    @Param('messageId') messageId: string,
+  ) {
+    const result = await session.unpinMessage(chatId, messageId);
+    return { success: result };
   }
 
   @Delete(':chatId/messages')
   @SessionApiParam
+  @CheckPolicies(CanSession(Action.Send, FromParam('session')))
   @ApiOperation({ summary: 'Clears all messages from the chat' })
+  @ChatIdApiParam
   clearMessages(
-    @SessionParam session: WhatsappSession,
+    @WorkingSessionParam session: WhatsappSession,
     @Param('chatId') chatId: string,
   ) {
     return session.clearMessages(chatId);
@@ -75,11 +219,12 @@ class ChatsController {
 
   @Delete(':chatId/messages/:messageId')
   @SessionApiParam
+  @CheckPolicies(CanSession(Action.Send, FromParam('session')))
   @ChatIdApiParam
   @MessageIdApiParam
   @ApiOperation({ summary: 'Deletes a message from the chat' })
   deleteMessage(
-    @SessionParam session: WhatsappSession,
+    @WorkingSessionParam session: WhatsappSession,
     @Param('chatId') chatId: string,
     @Param('messageId') messageId: string,
   ) {
@@ -88,11 +233,12 @@ class ChatsController {
 
   @Put(':chatId/messages/:messageId')
   @SessionApiParam
+  @CheckPolicies(CanSession(Action.Send, FromParam('session')))
   @ChatIdApiParam
   @MessageIdApiParam
   @ApiOperation({ summary: 'Edits a message in the chat' })
   editMessage(
-    @SessionParam session: WhatsappSession,
+    @WorkingSessionParam session: WhatsappSession,
     @Param('chatId') chatId: string,
     @Param('messageId') messageId: string,
     @Body() body: EditMessageRequest,
@@ -102,10 +248,11 @@ class ChatsController {
 
   @Post(':chatId/archive')
   @SessionApiParam
+  @CheckPolicies(CanSession(Action.Send, FromParam('session')))
   @ChatIdApiParam
   @ApiOperation({ summary: 'Archive the chat' })
   archiveChat(
-    @SessionParam session: WhatsappSession,
+    @WorkingSessionParam session: WhatsappSession,
     @Param('chatId') chatId: string,
   ) {
     return session.chatsArchiveChat(chatId);
@@ -113,14 +260,27 @@ class ChatsController {
 
   @Post(':chatId/unarchive')
   @SessionApiParam
+  @CheckPolicies(CanSession(Action.Send, FromParam('session')))
   @ChatIdApiParam
   @ApiOperation({ summary: 'Unarchive the chat' })
   unarchiveChat(
-    @SessionParam session: WhatsappSession,
+    @WorkingSessionParam session: WhatsappSession,
     @Param('chatId') chatId: string,
   ) {
     return session.chatsUnarchiveChat(chatId);
   }
+
+  @Post(':chatId/unread')
+  @SessionApiParam
+  @CheckPolicies(CanSession(Action.Send, FromParam('session')))
+  @ChatIdApiParam
+  @ApiOperation({ summary: 'Unread the chat' })
+  unreadChat(
+    @WorkingSessionParam session: WhatsappSession,
+    @Param('chatId') chatId: string,
+  ) {
+    return session.chatsUnreadChat(chatId);
+  }
 }
 
 export { ChatsController };

src/api/chatting.controller.ts

@@ -1,175 +1,414 @@
-import { Body, Controller, Get, Post, Put, Query } from '@nestjs/common';
-import { ApiOperation, ApiSecurity, ApiTags } from '@nestjs/swagger';
+import {
+  Body,
+  Controller,
+  Get,
+  Post,
+  Put,
+  Query,
+  UseGuards,
+  UsePipes,
+  ValidationPipe,
+} from '@nestjs/common';
+import { ApiBody, ApiOperation, ApiSecurity, ApiTags } from '@nestjs/swagger';
+import { WAHAValidationPipe } from '@waha/nestjs/pipes/WAHAValidationPipe';
+import {
+  GetChatMessagesFilter,
+  ReadChatMessagesQuery,
+  transformAck,
+} from '@waha/structures/chats.dto';
+import { SendButtonsRequest } from '@waha/structures/chatting.buttons.dto';
+import { SendListRequest } from '@waha/structures/chatting.list.dto';
 
 import { SessionManager } from '../core/abc/manager.abc';
 import {
   ChatRequest,
   CheckNumberStatusQuery,
   GetMessageQuery,
+  MessageButtonReply,
   MessageContactVcardRequest,
   MessageFileRequest,
+  MessageForwardRequest,
   MessageImageRequest,
+  MessageLinkCustomPreviewRequest,
   MessageLinkPreviewRequest,
   MessageLocationRequest,
   MessagePollRequest,
+  MessagePollVoteRequest,
   MessageReactionRequest,
   MessageReplyRequest,
   MessageStarRequest,
+  MessageStickerRequest,
   MessageTextQuery,
   MessageTextRequest,
   MessageVideoRequest,
   MessageVoiceRequest,
+  NewMessageIDResponse,
   SendSeenRequest,
   WANumberExistResult,
 } from '../structures/chatting.dto';
 import { WAMessage } from '../structures/responses.dto';
+import {
+  mentionsAll,
+  validateRequestMentions,
+} from '@waha/core/utils/mentions.all';
+import {
+  SessionApiParam,
+  WorkingSessionParam,
+} from '@waha/nestjs/params/SessionApiParam';
+import { WhatsappSession } from '@waha/core/abc/session.abc';
+import { PoliciesGuard } from '@waha/core/auth/policies.guard';
+import { CheckPolicies } from '@waha/core/auth/policies.decorator';
+import {
+  CanSession,
+  FromBody,
+  FromParam,
+  FromQuery,
+} from '@waha/core/auth/policies';
+
+import { Action } from '@waha/core/auth/casl.types';
 
 @ApiSecurity('api_key')
 @Controller('api')
-@ApiTags('chatting')
+@ApiTags('📤 Chatting')
+@UseGuards(PoliciesGuard)
 export class ChattingController {
   constructor(private manager: SessionManager) {}
 
-  @Get('/checkNumberStatus')
-  @ApiOperation({ summary: 'Check number status' })
-  async checkNumberStatus(
-    @Query() request: CheckNumberStatusQuery,
-  ): Promise<WANumberExistResult> {
-    const whatsapp = this.manager.getSession(request.session);
-    return whatsapp.checkNumberStatus(request);
-  }
-
-  @Post('/sendContactVcard')
-  sendContactVcard(@Body() request: MessageContactVcardRequest) {
-    const whatsapp = this.manager.getSession(request.session);
-    return whatsapp.sendContactVCard(request);
-  }
-
-  @Get('/sendText')
-  @ApiOperation({ summary: 'Send a text message', deprecated: true })
-  sendTextGet(@Query() query: MessageTextQuery) {
-    const whatsapp = this.manager.getSession(query.session);
-    const msg = new MessageTextRequest();
-    msg.chatId = query.phone;
-    msg.text = query.text;
-    return whatsapp.sendText(msg);
-  }
-
   @Post('/sendText')
   @ApiOperation({ summary: 'Send a text message' })
-  sendText(@Body() request: MessageTextRequest): Promise<WAMessage> {
-    const whatsapp = this.manager.getSession(request.session);
+  @CheckPolicies(CanSession(Action.Send, FromBody('session')))
+  async sendText(@Body() request: MessageTextRequest): Promise<WAMessage> {
+    const whatsapp = await this.manager.getWorkingSession(request.session);
+    if (mentionsAll(request)) {
+      validateRequestMentions(request);
+      request.mentions = await whatsapp.resolveMentionsAll(request.chatId);
+    }
     return whatsapp.sendText(request);
   }
 
-  @Post('/sendPoll')
-  @ApiOperation({
-    summary: 'Send a poll with options. You can use it as buttons replace',
-  })
-  sendPoll(@Body() request: MessagePollRequest) {
-    const whatsapp = this.manager.getSession(request.session);
-    return whatsapp.sendPoll(request);
-  }
-
-  @Post('/sendLocation')
-  sendLocation(@Body() request: MessageLocationRequest) {
-    const whatsapp = this.manager.getSession(request.session);
-    return whatsapp.sendLocation(request);
-  }
-
-  @Post('/sendLinkPreview')
-  sendLinkPreview(@Body() request: MessageLinkPreviewRequest) {
-    const whatsapp = this.manager.getSession(request.session);
-    return whatsapp.sendLinkPreview(request);
-  }
-
   @Post('/sendImage')
   @ApiOperation({
-    summary:
-      'Send an image. Either from an URL or base64 data - look at the request schemas for details.',
+    summary: 'Send an image',
+    description:
+      'Either from an URL or base64 data - look at the request schemas for details.',
   })
-  sendImage(@Body() request: MessageImageRequest) {
-    const whatsapp = this.manager.getSession(request.session);
+  @CheckPolicies(CanSession(Action.Send, FromBody('session')))
+  async sendImage(@Body() request: MessageImageRequest) {
+    const whatsapp = await this.manager.getWorkingSession(request.session);
+    if (mentionsAll(request)) {
+      validateRequestMentions(request);
+      request.mentions = await whatsapp.resolveMentionsAll(request.chatId);
+    }
     return whatsapp.sendImage(request);
   }
 
   @Post('/sendFile')
   @ApiOperation({
-    summary:
-      'Send a file. Either from an URL or base64 data - look at the request schemas for details.',
+    summary: 'Send a file',
+    description:
+      'Either from an URL or base64 data - look at the request schemas for details.',
   })
-  sendFile(@Body() request: MessageFileRequest) {
-    const whatsapp = this.manager.getSession(request.session);
+  @CheckPolicies(CanSession(Action.Send, FromBody('session')))
+  async sendFile(@Body() request: MessageFileRequest) {
+    const whatsapp = await this.manager.getWorkingSession(request.session);
+    if (mentionsAll(request)) {
+      validateRequestMentions(request);
+      request.mentions = await whatsapp.resolveMentionsAll(request.chatId);
+    }
     return whatsapp.sendFile(request);
   }
 
   @Post('/sendVoice')
   @ApiOperation({
-    summary:
-      'Send an voice message. Either from an URL or base64 data - look at the request schemas for details.',
+    summary: 'Send an voice message',
+    description:
+      'Either from an URL or base64 data - look at the request schemas for details.',
   })
-  sendVoice(@Body() request: MessageVoiceRequest) {
-    const whatsapp = this.manager.getSession(request.session);
+  @CheckPolicies(CanSession(Action.Send, FromBody('session')))
+  async sendVoice(@Body() request: MessageVoiceRequest) {
+    const whatsapp = await this.manager.getWorkingSession(request.session);
     return whatsapp.sendVoice(request);
   }
 
   @Post('/sendVideo')
   @ApiOperation({
-    summary:
-      'Send a video. Either from an URL or base64 data - look at the request schemas for details.',
+    summary: 'Send a video',
+    description:
+      'Either from an URL or base64 data - look at the request schemas for details.',
   })
-  sendVideo(@Body() request: MessageVideoRequest) {
-    const whatsapp = this.manager.getSession(request.session);
+  @CheckPolicies(CanSession(Action.Send, FromBody('session')))
+  async sendVideo(@Body() request: MessageVideoRequest) {
+    const whatsapp = await this.manager.getWorkingSession(request.session);
+    if (mentionsAll(request)) {
+      validateRequestMentions(request);
+      request.mentions = await whatsapp.resolveMentionsAll(request.chatId);
+    }
     return whatsapp.sendVideo(request);
   }
 
-  @Post('/reply')
-  @ApiOperation({ summary: 'Reply to a text message' })
-  reply(@Body() request: MessageReplyRequest) {
-    const whatsapp = this.manager.getSession(request.session);
-    return whatsapp.reply(request);
+  @Post('/sendSticker')
+  @ApiOperation({
+    summary: 'Send a sticker',
+    description:
+      'The image will not be converted. It must already be in WebP format. PNG and JPEG are not supported.',
+  })
+  @ApiBody({
+    type: MessageStickerRequest,
+    examples: {
+      url: {
+        summary: 'From URL',
+        value: {
+          session: 'default',
+          chatId: '11111111111@c.us',
+          reply_to: null,
+          file: {
+            url: 'https://www.gstatic.com/webp/gallery/1.webp',
+          },
+        },
+      },
+      base64webp: {
+        summary: 'From base64 WebP',
+        value: {
+          session: 'default',
+          chatId: '11111111111@c.us',
+          reply_to: null,
+          file: {
+            mimetype: 'image/webp',
+            data: 'your-base64-data-of-webp',
+          },
+        },
+      },
+    },
+  })
+  @CheckPolicies(CanSession(Action.Send, FromBody('session')))
+  async sendSticker(@Body() request: MessageStickerRequest) {
+    const whatsapp = await this.manager.getWorkingSession(request.session);
+    return whatsapp.sendSticker(request);
+  }
+
+  @Post('/send/link-custom-preview')
+  @ApiOperation({
+    summary: 'Send a text message with a CUSTOM link preview.',
+    description:
+      'You can use regular /api/sendText if you wanna send auto-generated link preview.',
+  })
+  @CheckPolicies(CanSession(Action.Send, FromBody('session')))
+  @UsePipes(new WAHAValidationPipe())
+  async sendLinkCustomPreview(
+    @Body() request: MessageLinkCustomPreviewRequest,
+  ): Promise<any> {
+    const whatsapp = await this.manager.getWorkingSession(request.session);
+    if (!request.text.includes(request.preview.url)) {
+      throw new Error(
+        '"text" must include the URL provided in the "preview.url"',
+      );
+    }
+    return whatsapp.sendLinkCustomPreview(request);
+  }
+
+  @Post('/sendButtons')
+  @ApiOperation({
+    summary: 'Send buttons message (interactive)',
+    description: 'Send Buttons',
+    deprecated: true,
+  })
+  @CheckPolicies(CanSession(Action.Send, FromBody('session')))
+  @UsePipes(new WAHAValidationPipe())
+  async sendButtons(@Body() request: SendButtonsRequest) {
+    const whatsapp = await this.manager.getWorkingSession(request.session);
+    return whatsapp.sendButtons(request);
+  }
+
+  @Post('/sendList')
+  @ApiOperation({
+    summary: 'Send a list message (interactive)',
+    description: 'Send a List message with sections and rows',
+  })
+  @CheckPolicies(CanSession(Action.Send, FromBody('session')))
+  @UsePipes(new WAHAValidationPipe())
+  async sendList(@Body() request: SendListRequest) {
+    const whatsapp = await this.manager.getWorkingSession(request.session);
+    return whatsapp.sendList(request);
+  }
+
+  @Post('/forwardMessage')
+  @CheckPolicies(CanSession(Action.Send, FromBody('session')))
+  async forwardMessage(
+    @Body() request: MessageForwardRequest,
+  ): Promise<WAMessage> {
+    const whatsapp = await this.manager.getWorkingSession(request.session);
+    return await whatsapp.forwardMessage(request);
   }
 
   @Post('/sendSeen')
-  sendSeen(@Body() chat: SendSeenRequest) {
-    const whatsapp = this.manager.getSession(chat.session);
+  @CheckPolicies(CanSession(Action.Send, FromBody('session')))
+  async sendSeen(@Body() chat: SendSeenRequest) {
+    const hasMessageId = chat.messageIds?.length > 0 || Boolean(chat.messageId);
+    if (!hasMessageId) {
+      const whatsapp = await this.manager.getWorkingSession(chat.session);
+      const query: ReadChatMessagesQuery = {
+        messages: null,
+        days: 7,
+      };
+      return whatsapp.readChatMessages(chat.chatId, query);
+    }
+    const whatsapp = await this.manager.getWorkingSession(chat.session);
     return whatsapp.sendSeen(chat);
   }
 
   @Post('/startTyping')
+  @CheckPolicies(CanSession(Action.Send, FromBody('session')))
   async startTyping(@Body() chat: ChatRequest) {
     // It's infinitive action
-    const whatsapp = this.manager.getSession(chat.session);
+    const whatsapp = await this.manager.getWorkingSession(chat.session);
     await whatsapp.startTyping(chat);
     return { result: true };
   }
 
   @Post('/stopTyping')
+  @CheckPolicies(CanSession(Action.Send, FromBody('session')))
   async stopTyping(@Body() chat: ChatRequest) {
-    const whatsapp = this.manager.getSession(chat.session);
+    const whatsapp = await this.manager.getWorkingSession(chat.session);
     await whatsapp.stopTyping(chat);
     return { result: true };
   }
 
   @Put('/reaction')
   @ApiOperation({ summary: 'React to a message with an emoji' })
-  setReaction(@Body() request: MessageReactionRequest) {
-    const whatsapp = this.manager.getSession(request.session);
+  @CheckPolicies(CanSession(Action.Send, FromBody('session')))
+  async setReaction(@Body() request: MessageReactionRequest) {
+    const whatsapp = await this.manager.getWorkingSession(request.session);
     return whatsapp.setReaction(request);
   }
 
   @Put('/star')
   @ApiOperation({ summary: 'Star or unstar a message' })
+  @CheckPolicies(CanSession(Action.Send, FromBody('session')))
   async setStar(@Body() request: MessageStarRequest) {
-    const whatsapp = this.manager.getSession(request.session);
+    const whatsapp = await this.manager.getWorkingSession(request.session);
     await whatsapp.setStar(request);
     return;
   }
 
+  @Post('/sendPoll')
+  @ApiOperation({
+    summary: 'Send a poll with options',
+    description: 'You can use it as buttons or list replacement',
+  })
+  @CheckPolicies(CanSession(Action.Send, FromBody('session')))
+  @UsePipes(new WAHAValidationPipe())
+  async sendPoll(@Body() request: MessagePollRequest) {
+    const whatsapp = await this.manager.getWorkingSession(request.session);
+    return whatsapp.sendPoll(request);
+  }
+
+  @Post('/sendPollVote')
+  @ApiOperation({
+    summary: 'Vote on a poll',
+    description: 'Cast vote(s) on an existing poll message',
+  })
+  @CheckPolicies(CanSession(Action.Send, FromBody('session')))
+  @UsePipes(new WAHAValidationPipe())
+  async sendPollVote(@Body() request: MessagePollVoteRequest) {
+    const whatsapp = await this.manager.getWorkingSession(request.session);
+    return whatsapp.sendPollVote(request);
+  }
+
+  @Post('/sendLocation')
+  @CheckPolicies(CanSession(Action.Send, FromBody('session')))
+  async sendLocation(@Body() request: MessageLocationRequest) {
+    const whatsapp = await this.manager.getWorkingSession(request.session);
+    return whatsapp.sendLocation(request);
+  }
+
+  @Post('/sendContactVcard')
+  @CheckPolicies(CanSession(Action.Send, FromBody('session')))
+  async sendContactVcard(@Body() request: MessageContactVcardRequest) {
+    const whatsapp = await this.manager.getWorkingSession(request.session);
+    return whatsapp.sendContactVCard(request);
+  }
+
+  @Post('/send/buttons/reply')
+  @ApiOperation({
+    summary: 'Reply on a button message',
+  })
+  @CheckPolicies(CanSession(Action.Send, FromBody('session')))
+  @UsePipes(new ValidationPipe({ transform: true, whitelist: true }))
+  async sendButtonsReply(@Body() request: MessageButtonReply) {
+    const whatsapp = await this.manager.getWorkingSession(request.session);
+    return whatsapp.sendButtonsReply(request);
+  }
+
+  @Get('/sendText')
+  @ApiOperation({ summary: 'Send a text message', deprecated: true })
+  @CheckPolicies(CanSession(Action.Send, FromQuery('session')))
+  async sendTextGet(@Query() query: MessageTextQuery) {
+    const whatsapp = await this.manager.getWorkingSession(query.session);
+    const msg = new MessageTextRequest();
+    msg.chatId = query.phone;
+    msg.text = query.text;
+    return whatsapp.sendText(msg);
+  }
+
   @Get('/messages')
-  @ApiOperation({ summary: 'Get messages in a chat' })
-  getMessages(@Query() query: GetMessageQuery) {
-    const whatsapp = this.manager.getSession(query.session);
-    return whatsapp.getMessages(query);
+  @ApiOperation({
+    summary: 'Get messages in a chat',
+    description: 'DEPRECATED. Use "GET /api/chats/{id}/messages" instead',
+    deprecated: true,
+  })
+  @CheckPolicies(CanSession(Action.Read, FromQuery('session')))
+  @UsePipes(new ValidationPipe({ transform: true, whitelist: true }))
+  async getMessages(
+    @Query() query: GetMessageQuery,
+    @Query() filter: GetChatMessagesFilter,
+  ) {
+    filter = transformAck(filter);
+    const whatsapp = await this.manager.getWorkingSession(query.session);
+    return whatsapp.getChatMessages(query.chatId, query, filter);
+  }
+
+  @Get('/checkNumberStatus')
+  @ApiOperation({
+    summary: 'Check number status',
+    description: 'DEPRECATED. Use "POST /contacts/check-exists" instead',
+    deprecated: true,
+  })
+  @CheckPolicies(CanSession(Action.Read, FromQuery('session')))
+  async DEPRECATED_checkNumberStatus(
+    @Query() request: CheckNumberStatusQuery,
+  ): Promise<WANumberExistResult> {
+    const whatsapp = await this.manager.getWorkingSession(request.session);
+    return whatsapp.checkNumberStatus(request);
+  }
+
+  @Post('/reply')
+  @ApiOperation({
+    summary:
+      'DEPRECATED - you can set "reply_to" field when sending text, image, etc',
+    deprecated: true,
+  })
+  @CheckPolicies(CanSession(Action.Send, FromBody('session')))
+  async reply(@Body() request: MessageReplyRequest) {
+    const whatsapp = await this.manager.getWorkingSession(request.session);
+    return whatsapp.reply(request);
+  }
+
+  @Post('/sendLinkPreview')
+  @ApiOperation({ deprecated: true })
+  @CheckPolicies(CanSession(Action.Send, FromBody('session')))
+  async sendLinkPreview_DEPRECATED(@Body() request: MessageLinkPreviewRequest) {
+    const whatsapp = await this.manager.getWorkingSession(request.session);
+    return whatsapp.sendLinkPreview(request);
+  }
+
+  @Get('/:session/new-message-id')
+  @SessionApiParam
+  @ApiOperation({ summary: 'Generate a new message ID' })
+  @CheckPolicies(CanSession(Action.Read, FromParam('session')))
+  async getNewMessageId(
+    @WorkingSessionParam session: WhatsappSession,
+  ): Promise<NewMessageIDResponse> {
+    const id = await session.generateNewMessageId();
+    return { id: id };
   }
 }

src/api/contacts.controller.ts

@@ -1,4 +1,13 @@
-import { Body, Controller, Get, Post, Query } from '@nestjs/common';
+import {
+  Body,
+  Controller,
+  Get,
+  Post,
+  Query,
+  UseGuards,
+  UsePipes,
+  ValidationPipe,
+} from '@nestjs/common';
 import { ApiOperation, ApiSecurity, ApiTags } from '@nestjs/swagger';
 
 import { SessionManager } from '../core/abc/manager.abc';
@@ -7,71 +16,101 @@ import {
   CheckNumberStatusQuery,
   WANumberExistResult,
 } from '../structures/chatting.dto';
-import { ContactQuery, ContactRequest } from '../structures/contacts.dto';
+import {
+  ContactProfilePictureQuery,
+  ContactQuery,
+  ContactRequest,
+  ContactsPaginationParams,
+} from '../structures/contacts.dto';
+import { PoliciesGuard } from '@waha/core/auth/policies.guard';
+import { CheckPolicies } from '@waha/core/auth/policies.decorator';
+import { CanSession, FromBody, FromQuery } from '@waha/core/auth/policies';
+
+import { Action } from '@waha/core/auth/casl.types';
 
 @ApiSecurity('api_key')
 @Controller('api/contacts')
-@ApiTags('contacts')
+@ApiTags('👤 Contacts')
+@UseGuards(PoliciesGuard)
 export class ContactsController {
   constructor(private manager: SessionManager) {}
 
-  @Get('/')
-  @ApiOperation({
-    summary:
-      'Get contact basic info. The method always return result, even if the phone number is not registered in WhatsApp. For that - use /check-exists endpoint below.',
-  })
-  get(@Query() query: ContactQuery) {
-    const whatsapp = this.manager.getSession(query.session);
-    return whatsapp.getContact(query);
-  }
-
   @Get('/all')
   @ApiOperation({ summary: 'Get all contacts' })
-  getAll(@Query() query: SessionQuery) {
-    const whatsapp = this.manager.getSession(query.session);
-    return whatsapp.getContacts();
+  @CheckPolicies(CanSession(Action.Read, FromQuery('session')))
+  @UsePipes(new ValidationPipe({ transform: true, whitelist: true }))
+  async getAll(
+    @Query() query: SessionQuery,
+    @Query() pagination: ContactsPaginationParams,
+  ) {
+    const whatsapp = await this.manager.getWorkingSession(query.session);
+    return whatsapp.getContacts(pagination);
+  }
+
+  @Get('/')
+  @ApiOperation({
+    summary: 'Get contact basic info',
+    description:
+      'The method always return result, even if the phone number is not registered in WhatsApp. For that - use /contacts/check-exists endpoint below.',
+  })
+  @CheckPolicies(CanSession(Action.Read, FromQuery('session')))
+  async get(@Query() query: ContactQuery) {
+    const whatsapp = await this.manager.getWorkingSession(query.session);
+    return whatsapp.getContact(query);
   }
 
   @Get('/check-exists')
   @ApiOperation({ summary: 'Check phone number is registered in WhatsApp.' })
+  @CheckPolicies(CanSession(Action.Read, FromQuery('session')))
   async checkExists(
     @Query() request: CheckNumberStatusQuery,
   ): Promise<WANumberExistResult> {
-    const whatsapp = this.manager.getSession(request.session);
+    const whatsapp = await this.manager.getWorkingSession(request.session);
     return whatsapp.checkNumberStatus(request);
   }
 
   @Get('/about')
   @ApiOperation({
-    summary:
-      'Gets the Contact\'s current "about" info. Returns null if you don\'t have permission to read their status.',
+    summary: 'Gets the Contact\'s "about" info',
+    description:
+      'Returns null if you do not have permission to read their status.',
   })
-  getAbout(@Query() query: ContactQuery) {
-    const whatsapp = this.manager.getSession(query.session);
+  @CheckPolicies(CanSession(Action.Read, FromQuery('session')))
+  async getAbout(@Query() query: ContactQuery) {
+    const whatsapp = await this.manager.getWorkingSession(query.session);
     return whatsapp.getContactAbout(query);
   }
 
   @Get('/profile-picture')
   @ApiOperation({
-    summary:
-      "Returns the contact's profile picture URL, if privacy settings allow it.",
+    summary: "Get contact's profile picture URL",
+    description:
+      'If privacy settings do not allow to get the picture, the method will return null.',
   })
-  getProfilePicture(@Query() query: ContactQuery) {
-    const whatsapp = this.manager.getSession(query.session);
-    return whatsapp.getContactProfilePicture(query);
+  @CheckPolicies(CanSession(Action.Read, FromQuery('session')))
+  @UsePipes(new ValidationPipe({ transform: true, whitelist: true }))
+  async getProfilePicture(@Query() query: ContactProfilePictureQuery) {
+    const whatsapp = await this.manager.getWorkingSession(query.session);
+    const url = await whatsapp.getContactProfilePicture(
+      query.contactId,
+      query.refresh,
+    );
+    return { profilePictureURL: url };
   }
 
   @Post('/block')
   @ApiOperation({ summary: 'Block contact' })
-  block(@Body() request: ContactRequest) {
-    const whatsapp = this.manager.getSession(request.session);
+  @CheckPolicies(CanSession(Action.Send, FromBody('session')))
+  async block(@Body() request: ContactRequest) {
+    const whatsapp = await this.manager.getWorkingSession(request.session);
     return whatsapp.blockContact(request);
   }
 
   @Post('/unblock')
   @ApiOperation({ summary: 'Unblock contact' })
-  unblock(@Body() request: ContactRequest) {
-    const whatsapp = this.manager.getSession(request.session);
+  @CheckPolicies(CanSession(Action.Send, FromBody('session')))
+  async unblock(@Body() request: ContactRequest) {
+    const whatsapp = await this.manager.getWorkingSession(request.session);
     return whatsapp.unblockContact(request);
   }
 }

src/api/contacts.session.controller.ts

@@ -0,0 +1,74 @@
+import {
+  Body,
+  Controller,
+  Get,
+  Param,
+  Put,
+  UseGuards,
+  UsePipes,
+} from '@nestjs/common';
+import { ApiOperation, ApiParam, ApiSecurity, ApiTags } from '@nestjs/swagger';
+import { PoliciesGuard } from '@waha/core/auth/policies.guard';
+import { CheckPolicies } from '@waha/core/auth/policies.decorator';
+import { CanSession, FromParam } from '@waha/core/auth/policies';
+import { WhatsappSession } from '@waha/core/abc/session.abc';
+import { ChatIdApiParam } from '@waha/nestjs/params/ChatIdApiParam';
+import {
+  SessionApiParam,
+  WorkingSessionParam,
+} from '@waha/nestjs/params/SessionApiParam';
+import { WAHAValidationPipe } from '@waha/nestjs/pipes/WAHAValidationPipe';
+
+import { SessionManager } from '../core/abc/manager.abc';
+import { Result } from '../structures/base.dto';
+import { ContactUpdateBody } from '../structures/contacts.dto';
+import { Action } from '@waha/core/auth/casl.types';
+
+@ApiSecurity('api_key')
+@Controller('api/:session/contacts')
+@ApiTags('👤 Contacts')
+@UseGuards(PoliciesGuard)
+export class ContactsSessionController {
+  constructor(private manager: SessionManager) {}
+
+  @Get('/:id')
+  @SessionApiParam
+  @CheckPolicies(CanSession(Action.Read, FromParam('session')))
+  @ApiParam({
+    name: 'id',
+    required: true,
+    type: 'string',
+    description: 'Contact ID',
+    example: '123456789@c.us',
+  })
+  @ApiOperation({
+    summary: 'Get contact basic info',
+    description:
+      'The method always return result, even if the phone number is not registered in WhatsApp. For that - use /contacts/check-exists endpoint below.',
+  })
+  async get(
+    @WorkingSessionParam session: WhatsappSession,
+    @Param('id') id: string,
+  ) {
+    return session.getContact({ session: session.name, contactId: id });
+  }
+
+  @Put('/:chatId')
+  @SessionApiParam
+  @ChatIdApiParam
+  @CheckPolicies(CanSession(Action.Send, FromParam('session')))
+  @ApiOperation({
+    summary: 'Create or update contact',
+    description:
+      'Create or update contact on the phone address book. May not work if you have installed many WhatsApp apps on the same phone',
+  })
+  @UsePipes(new WAHAValidationPipe())
+  async put(
+    @WorkingSessionParam session: WhatsappSession,
+    @Param('chatId') chatId: string,
+    @Body() body: ContactUpdateBody,
+  ): Promise<Result> {
+    await session.upsertContact(chatId, body);
+    return { success: true };
+  }
+}

src/api/events.controller.ts

@@ -0,0 +1,58 @@
+import {
+  Body,
+  Controller,
+  Param,
+  Post,
+  UseGuards,
+  UsePipes,
+  ValidationPipe,
+} from '@nestjs/common';
+import { ApiOperation, ApiSecurity, ApiTags } from '@nestjs/swagger';
+import { WhatsappSession } from '@waha/core/abc/session.abc';
+import {
+  SessionApiParam,
+  WorkingSessionParam,
+} from '@waha/nestjs/params/SessionApiParam';
+
+import { SessionManager } from '../core/abc/manager.abc';
+import {
+  EventCancelRequest,
+  EventMessageRequest,
+} from '../structures/events.dto';
+import { WAMessage } from '../structures/responses.dto';
+import { PoliciesGuard } from '@waha/core/auth/policies.guard';
+import { CheckPolicies } from '@waha/core/auth/policies.decorator';
+import { CanSession, FromParam } from '@waha/core/auth/policies';
+
+import { Action } from '@waha/core/auth/casl.types';
+
+@ApiSecurity('api_key')
+@Controller('api/:session/events')
+@ApiTags('📅 Events')
+@UseGuards(PoliciesGuard)
+@CheckPolicies(CanSession(Action.Send, FromParam('session')))
+export class EventsController {
+  constructor(private manager: SessionManager) {}
+
+  @Post()
+  @ApiOperation({ summary: 'Send an event message' })
+  @UsePipes(new ValidationPipe())
+  @SessionApiParam
+  async sendEvent(
+    @WorkingSessionParam session: WhatsappSession,
+    @Body() request: EventMessageRequest,
+  ): Promise<WAMessage> {
+    return session.sendEvent(request);
+  }
+
+  // @Post(':id/cancel')
+  // @ApiOperation({ summary: 'Cancel an event by ID' })
+  // @UsePipes(new ValidationPipe())
+  // @SessionApiParam
+  // async cancelEvent(
+  //   @WorkingSessionParam session: WhatsappSession,
+  //   @Param('id') id: string,
+  // ): Promise<WAMessage> {
+  //   return session.cancelEvent(id);
+  // }
+}

src/api/groups.controller.ts

@@ -3,129 +3,228 @@ import {
   Controller,
   Delete,
   Get,
+  HttpCode,
+  HttpStatus,
   Param,
   Post,
   Put,
+  Query,
+  UseGuards,
+  UsePipes,
+  ValidationPipe,
 } from '@nestjs/common';
 import { ApiOperation, ApiSecurity, ApiTags } from '@nestjs/swagger';
+import { GroupIdApiParam } from '@waha/nestjs/params/ChatIdApiParam';
+import {
+  SessionApiParam,
+  WorkingSessionParam,
+} from '@waha/nestjs/params/SessionApiParam';
+import { CountResponse, Result } from '@waha/structures/base.dto';
+import {
+  ChatPictureQuery,
+  ChatPictureResponse,
+} from '@waha/structures/chats.dto';
+import { ProfilePictureRequest } from '@waha/structures/profile.dto';
 
 import { SessionManager } from '../core/abc/manager.abc';
-import { WhatsappSession } from '../core/abc/session.abc';
+import { parseGroupInviteLink, WhatsappSession } from '../core/abc/session.abc';
 import {
   CreateGroupRequest,
   DescriptionRequest,
+  GroupField,
+  GroupJoinRequest,
+  GroupJoinRequestResult,
+  GroupParticipant,
+  GroupsListFields,
+  GroupsPaginationParams,
+  JoinGroupRequest,
+  JoinGroupResponse,
   ParticipantsRequest,
+  SettingsMemberAddMode,
+  SettingsMembershipApproval,
   SettingsSecurityChangeInfo,
   SubjectRequest,
 } from '../structures/groups.dto';
-import { SessionApiParam, SessionParam } from './helpers';
+import { PoliciesGuard } from '@waha/core/auth/policies.guard';
+import { CheckPolicies } from '@waha/core/auth/policies.decorator';
+import { CanSession, FromParam } from '@waha/core/auth/policies';
+
+import { Action } from '@waha/core/auth/casl.types';
 
 @ApiSecurity('api_key')
 @Controller('api/:session/groups')
-@ApiTags('groups')
+@ApiTags('👥 Groups')
+@UseGuards(PoliciesGuard)
 export class GroupsController {
   constructor(private manager: SessionManager) {}
 
   @Post('')
   @SessionApiParam
+  @CheckPolicies(CanSession(Action.Send, FromParam('session')))
   @ApiOperation({ summary: 'Create a new group.' })
   createGroup(
-    @SessionParam session: WhatsappSession,
+    @WorkingSessionParam session: WhatsappSession,
     @Body() request: CreateGroupRequest,
   ) {
     return session.createGroup(request);
   }
 
+  @Get('join-info')
+  @SessionApiParam
+  @CheckPolicies(CanSession(Action.Read, FromParam('session')))
+  @ApiOperation({ summary: 'Get info about the group before joining.' })
+  async joinInfoGroup(
+    @WorkingSessionParam session: WhatsappSession,
+    @Query() query: JoinGroupRequest,
+  ): Promise<any> {
+    const code = parseGroupInviteLink(query.code);
+    return session.joinInfoGroup(code);
+  }
+
+  @Post('join')
+  @HttpCode(HttpStatus.OK)
+  @SessionApiParam
+  @CheckPolicies(CanSession(Action.Send, FromParam('session')))
+  @ApiOperation({ summary: 'Join group via code' })
+  async joinGroup(
+    @WorkingSessionParam session: WhatsappSession,
+    @Body() request: JoinGroupRequest,
+  ): Promise<JoinGroupResponse> {
+    const code = parseGroupInviteLink(request.code);
+    const id = await session.joinGroup(code);
+    return { id: id };
+  }
+
   @Get('')
   @SessionApiParam
+  @CheckPolicies(CanSession(Action.Read, FromParam('session')))
   @ApiOperation({ summary: 'Get all groups.' })
-  getGroups(@SessionParam session: WhatsappSession) {
-    return session.getGroups();
+  @UsePipes(new ValidationPipe({ transform: true, whitelist: true }))
+  async getGroups(
+    @WorkingSessionParam session: WhatsappSession,
+    @Query() pagination: GroupsPaginationParams,
+    @Query() fields: GroupsListFields,
+  ) {
+    let groups: any = await session.getGroups(pagination);
+    groups = session.filterGroupsFields(groups, fields);
+    return groups;
+  }
+
+  @Get('/count')
+  @SessionApiParam
+  @CheckPolicies(CanSession(Action.Read, FromParam('session')))
+  @ApiOperation({ summary: 'Get the number of groups.' })
+  @UsePipes(new ValidationPipe({ transform: true, whitelist: true }))
+  async getGroupsCount(
+    @WorkingSessionParam session: WhatsappSession,
+  ): Promise<CountResponse> {
+    const data: any = await session.getGroups({});
+    const groups: any[] = Array.isArray(data) ? data : Object.values(data);
+    return {
+      count: groups.length,
+    };
+  }
+
+  @Post('refresh')
+  @HttpCode(HttpStatus.OK)
+  @SessionApiParam
+  @CheckPolicies(CanSession(Action.Send, FromParam('session')))
+  @ApiOperation({ summary: 'Refresh groups from the server.' })
+  @UsePipes(new ValidationPipe({ transform: true, whitelist: true }))
+  async refreshGroups(@WorkingSessionParam session: WhatsappSession) {
+    return { success: await session.refreshGroups() };
   }
 
   @Get(':id')
+  @GroupIdApiParam
   @SessionApiParam
+  @CheckPolicies(CanSession(Action.Read, FromParam('session')))
   @ApiOperation({ summary: 'Get the group.' })
-  getGroup(@SessionParam session: WhatsappSession, @Param('id') id: string) {
+  getGroup(
+    @WorkingSessionParam session: WhatsappSession,
+    @Param('id') id: string,
+  ) {
     return session.getGroup(id);
   }
 
-  @Put(':id/settings/security/info-admin-only')
-  @SessionApiParam
-  @ApiOperation({
-    summary:
-      'Updates the group settings to only allow admins to edit group info (title, description, photo).',
-  })
-  setInfoAdminOnly(
-    @SessionParam session: WhatsappSession,
-    @Param('id') id: string,
-    @Body() request: SettingsSecurityChangeInfo,
-  ) {
-    return session.setInfoAdminsOnly(id, request.adminsOnly);
-  }
-
-  @Get(':id/settings/security/info-admin-only')
-  @SessionApiParam
-  @ApiOperation({
-    summary:
-      'Gets the group settings to only allow admins to edit group info (title, description, photo).',
-  })
-  getInfoAdminOnly(
-    @SessionParam session: WhatsappSession,
-    @Param('id') id: string,
-  ): Promise<SettingsSecurityChangeInfo> {
-    return session.getInfoAdminsOnly(id);
-  }
-
-  @Put(':id/settings/security/messages-admin-only')
-  @SessionApiParam
-  @ApiOperation({
-    summary:
-      'Updates the group settings to only allow admins to send messages.',
-  })
-  setMessagesAdminOnly(
-    @SessionParam session: WhatsappSession,
-    @Param('id') id: string,
-    @Body() request: SettingsSecurityChangeInfo,
-  ) {
-    return session.setMessagesAdminsOnly(id, request.adminsOnly);
-  }
-
-  @Get(':id/settings/security/messages-admin-only')
-  @SessionApiParam
-  @ApiOperation({
-    summary: 'Gets the group settings to only allow admins to send messages.',
-  })
-  getMessagesAdminOnly(
-    @SessionParam session: WhatsappSession,
-    @Param('id') id: string,
-  ): Promise<SettingsSecurityChangeInfo> {
-    return session.getMessagesAdminsOnly(id);
-  }
-
   @Delete(':id')
   @SessionApiParam
+  @GroupIdApiParam
+  @CheckPolicies(CanSession(Action.Send, FromParam('session')))
   @ApiOperation({ summary: 'Delete the group.' })
-  deleteGroup(@SessionParam session: WhatsappSession, @Param('id') id: string) {
+  deleteGroup(
+    @WorkingSessionParam session: WhatsappSession,
+    @Param('id') id: string,
+  ) {
     return session.deleteGroup(id);
   }
 
   @Post(':id/leave')
+  @HttpCode(HttpStatus.OK)
   @SessionApiParam
+  @GroupIdApiParam
+  @CheckPolicies(CanSession(Action.Send, FromParam('session')))
   @ApiOperation({ summary: 'Leave the group.' })
-  leaveGroup(@SessionParam session: WhatsappSession, @Param('id') id: string) {
+  leaveGroup(
+    @WorkingSessionParam session: WhatsappSession,
+    @Param('id') id: string,
+  ) {
     return session.leaveGroup(id);
   }
 
+  @Get(':id/picture')
+  @SessionApiParam
+  @GroupIdApiParam
+  @CheckPolicies(CanSession(Action.Read, FromParam('session')))
+  @ApiOperation({ summary: 'Get group picture' })
+  @UsePipes(new ValidationPipe({ transform: true, whitelist: true }))
+  async getChatPicture(
+    @WorkingSessionParam session: WhatsappSession,
+    @Param('id') id: string,
+    @Query() query: ChatPictureQuery,
+  ): Promise<ChatPictureResponse> {
+    const url = await session.getContactProfilePicture(id, query.refresh);
+    return { url: url };
+  }
+
+  @Put(':id/picture')
+  @SessionApiParam
+  @GroupIdApiParam
+  @CheckPolicies(CanSession(Action.Send, FromParam('session')))
+  @ApiOperation({ summary: 'Set group picture' })
+  async setPicture(
+    @Param('id') id: string,
+    @WorkingSessionParam session: WhatsappSession,
+    @Body() request: ProfilePictureRequest,
+  ): Promise<Result> {
+    const success = await session.updateGroupPicture(id, request.file);
+    return { success: success ?? true };
+  }
+
+  @Delete(':id/picture')
+  @SessionApiParam
+  @GroupIdApiParam
+  @CheckPolicies(CanSession(Action.Send, FromParam('session')))
+  @ApiOperation({ summary: 'Delete group picture' })
+  async deletePicture(
+    @Param('id') id: string,
+    @WorkingSessionParam session: WhatsappSession,
+  ): Promise<Result> {
+    const success = await session.updateGroupPicture(id, null);
+    return { success: success || true };
+  }
+
   @Put(':id/description')
   @ApiOperation({
-    summary:
-      'Updates the group description.\n' +
-      'Returns true if the subject was properly updated. This can return false if the user does not have the necessary permissions.\n',
+    summary: 'Updates the group description.',
+    description:
+      'Returns "true" if the subject was properly updated. This can return "false" if the user does not have the necessary permissions.',
   })
   @SessionApiParam
+  @GroupIdApiParam
+  @CheckPolicies(CanSession(Action.Send, FromParam('session')))
   setDescription(
-    @SessionParam session: WhatsappSession,
+    @WorkingSessionParam session: WhatsappSession,
     @Param('id') id: string,
     @Body() request: DescriptionRequest,
   ) {
@@ -134,37 +233,224 @@ export class GroupsController {
 
   @Put(':id/subject')
   @SessionApiParam
+  @GroupIdApiParam
+  @CheckPolicies(CanSession(Action.Send, FromParam('session')))
   @ApiOperation({
-    summary:
-      'Updates the group subject.\n' +
-      'Returns true if the subject was properly updated. This can return false if the user does not have the necessary permissions.\n',
+    summary: 'Updates the group subject',
+    description:
+      'Returns "true" if the subject was properly updated. This can return "false" if the user does not have the necessary permissions.',
   })
   setSubject(
-    @SessionParam session: WhatsappSession,
+    @WorkingSessionParam session: WhatsappSession,
     @Param('id') id: string,
     @Body() request: SubjectRequest,
   ) {
     return session.setSubject(id, request.subject);
   }
 
+  @Put(':id/settings/security/info-admin-only')
+  @SessionApiParam
+  @GroupIdApiParam
+  @CheckPolicies(CanSession(Action.Send, FromParam('session')))
+  @ApiOperation({
+    summary: 'Updates the group "info admin only" settings.',
+    description:
+      'You can allow only admins to edit group info (title, description, photo).',
+  })
+  setInfoAdminOnly(
+    @WorkingSessionParam session: WhatsappSession,
+    @Param('id') id: string,
+    @Body() request: SettingsSecurityChangeInfo,
+  ) {
+    return session.setInfoAdminsOnly(id, request.adminsOnly);
+  }
+
+  @Get(':id/settings/security/info-admin-only')
+  @SessionApiParam
+  @GroupIdApiParam
+  @CheckPolicies(CanSession(Action.Read, FromParam('session')))
+  @ApiOperation({
+    summary: "Get the group's 'info admin only' settings.",
+    description:
+      'You can allow only admins to edit group info (title, description, photo).',
+  })
+  getInfoAdminOnly(
+    @WorkingSessionParam session: WhatsappSession,
+    @Param('id') id: string,
+  ): Promise<SettingsSecurityChangeInfo> {
+    return session.getInfoAdminsOnly(id);
+  }
+
+  @Put(':id/settings/security/messages-admin-only')
+  @SessionApiParam
+  @GroupIdApiParam
+  @CheckPolicies(CanSession(Action.Send, FromParam('session')))
+  @ApiOperation({
+    summary: 'Update settings - who can send messages',
+    description:
+      'Updates the group settings to only allow admins to send messages.',
+  })
+  setMessagesAdminOnly(
+    @WorkingSessionParam session: WhatsappSession,
+    @Param('id') id: string,
+    @Body() request: SettingsSecurityChangeInfo,
+  ) {
+    return session.setMessagesAdminsOnly(id, request.adminsOnly);
+  }
+
+  @Get(':id/settings/security/messages-admin-only')
+  @SessionApiParam
+  @GroupIdApiParam
+  @CheckPolicies(CanSession(Action.Read, FromParam('session')))
+  @ApiOperation({
+    summary: 'Get settings - who can send messages',
+    description: 'The group settings to only allow admins to send messages.',
+  })
+  getMessagesAdminOnly(
+    @WorkingSessionParam session: WhatsappSession,
+    @Param('id') id: string,
+  ): Promise<SettingsSecurityChangeInfo> {
+    return session.getMessagesAdminsOnly(id);
+  }
+
+  @Put(':id/settings/security/member-add-mode')
+  @SessionApiParam
+  @GroupIdApiParam
+  @CheckPolicies(CanSession(Action.Send, FromParam('session')))
+  @ApiOperation({
+    summary: 'Update settings - who can add new members',
+    description:
+      'Updates the group settings for who can add new members to the group - all members or admins only.',
+  })
+  setMemberAddMode(
+    @WorkingSessionParam session: WhatsappSession,
+    @Param('id') id: string,
+    @Body() request: SettingsMemberAddMode,
+  ) {
+    return session.setMemberAddMode(id, request.membersCanAddNewMember);
+  }
+
+  @Get(':id/settings/security/member-add-mode')
+  @SessionApiParam
+  @GroupIdApiParam
+  @CheckPolicies(CanSession(Action.Read, FromParam('session')))
+  @ApiOperation({
+    summary: 'Get settings - who can add new members',
+    description:
+      'The group settings for who can add new members to the group - all members or admins only.',
+  })
+  getMemberAddMode(
+    @WorkingSessionParam session: WhatsappSession,
+    @Param('id') id: string,
+  ): Promise<SettingsMemberAddMode> {
+    return session.getMemberAddMode(id);
+  }
+
+  @Put(':id/settings/security/membership-approval')
+  @SessionApiParam
+  @GroupIdApiParam
+  @CheckPolicies(CanSession(Action.Send, FromParam('session')))
+  @ApiOperation({
+    summary: 'Update settings - approve new members',
+    description:
+      'Enables or disables admin approval for users requesting to join the group.',
+  })
+  setMembershipApprovalMode(
+    @WorkingSessionParam session: WhatsappSession,
+    @Param('id') id: string,
+    @Body() request: SettingsMembershipApproval,
+  ): Promise<boolean> {
+    return session.setMembershipApprovalMode(
+      id,
+      request.newMembersApprovalRequired,
+    );
+  }
+
+  @Get(':id/settings/security/membership-approval')
+  @SessionApiParam
+  @GroupIdApiParam
+  @CheckPolicies(CanSession(Action.Read, FromParam('session')))
+  @ApiOperation({
+    summary: 'Get settings - approve new members',
+    description:
+      'Returns whether admin approval is required for users requesting to join the group.',
+  })
+  getMembershipApprovalMode(
+    @WorkingSessionParam session: WhatsappSession,
+    @Param('id') id: string,
+  ): Promise<SettingsMembershipApproval> {
+    return session.getMembershipApprovalMode(id);
+  }
+
+  @Get(':id/participants/join-requests')
+  @SessionApiParam
+  @GroupIdApiParam
+  @CheckPolicies(CanSession(Action.Read, FromParam('session')))
+  @ApiOperation({
+    summary: 'Get pending requests to join the group',
+  })
+  getGroupJoinRequests(
+    @WorkingSessionParam session: WhatsappSession,
+    @Param('id') id: string,
+  ): Promise<GroupJoinRequest[]> {
+    return session.getGroupJoinRequests(id);
+  }
+
+  @Post(':id/participants/join-requests/approve')
+  @HttpCode(HttpStatus.OK)
+  @SessionApiParam
+  @GroupIdApiParam
+  @CheckPolicies(CanSession(Action.Send, FromParam('session')))
+  @ApiOperation({
+    summary: 'Approve pending requests to join the group',
+  })
+  approveGroupJoinRequests(
+    @WorkingSessionParam session: WhatsappSession,
+    @Param('id') id: string,
+    @Body() request: ParticipantsRequest,
+  ): Promise<GroupJoinRequestResult[]> {
+    return session.approveGroupJoinRequests(id, request);
+  }
+
+  @Post(':id/participants/join-requests/reject')
+  @HttpCode(HttpStatus.OK)
+  @SessionApiParam
+  @GroupIdApiParam
+  @CheckPolicies(CanSession(Action.Send, FromParam('session')))
+  @ApiOperation({
+    summary: 'Reject pending requests to join the group',
+  })
+  rejectGroupJoinRequests(
+    @WorkingSessionParam session: WhatsappSession,
+    @Param('id') id: string,
+    @Body() request: ParticipantsRequest,
+  ): Promise<GroupJoinRequestResult[]> {
+    return session.rejectGroupJoinRequests(id, request);
+  }
+
   @Get(':id/invite-code')
   @SessionApiParam
-  @ApiOperation({ summary: 'Gets the invite code for a specific group.' })
+  @GroupIdApiParam
+  @CheckPolicies(CanSession(Action.Read, FromParam('session')))
+  @ApiOperation({ summary: 'Gets the invite code for the group.' })
   getInviteCode(
-    @SessionParam session: WhatsappSession,
+    @WorkingSessionParam session: WhatsappSession,
     @Param('id') id: string,
   ): Promise<string> {
     return session.getInviteCode(id);
   }
 
   @Post(':id/invite-code/revoke')
+  @HttpCode(HttpStatus.OK)
   @SessionApiParam
+  @GroupIdApiParam
+  @CheckPolicies(CanSession(Action.Send, FromParam('session')))
   @ApiOperation({
     summary:
       'Invalidates the current group invite code and generates a new one.',
   })
   revokeInviteCode(
-    @SessionParam session: WhatsappSession,
+    @WorkingSessionParam session: WhatsappSession,
     @Param('id') id: string,
   ): Promise<string> {
     return session.revokeInviteCode(id);
@@ -172,19 +458,36 @@ export class GroupsController {
 
   @Get(':id/participants/')
   @SessionApiParam
-  @ApiOperation({ summary: 'Get a list of participants by in the group.' })
+  @GroupIdApiParam
+  @CheckPolicies(CanSession(Action.Read, FromParam('session')))
+  @ApiOperation({ summary: 'Get participants' })
   getParticipants(
-    @SessionParam session: WhatsappSession,
+    @WorkingSessionParam session: WhatsappSession,
     @Param('id') id: string,
   ) {
     return session.getParticipants(id);
   }
 
-  @Post(':id/participants/add')
+  @Get(':id/participants/v2')
+  @GroupIdApiParam
   @SessionApiParam
-  @ApiOperation({ summary: 'Adds a list of participants by ID to the group.' })
+  @CheckPolicies(CanSession(Action.Read, FromParam('session')))
+  @ApiOperation({ summary: 'Get group participants.' })
+  getGroupParticipants(
+    @WorkingSessionParam session: WhatsappSession,
+    @Param('id') id: string,
+  ): Promise<GroupParticipant[]> {
+    return session.getGroupParticipants(id);
+  }
+
+  @Post(':id/participants/add')
+  @HttpCode(HttpStatus.OK)
+  @SessionApiParam
+  @GroupIdApiParam
+  @CheckPolicies(CanSession(Action.Send, FromParam('session')))
+  @ApiOperation({ summary: 'Add participants' })
   addParticipants(
-    @SessionParam session: WhatsappSession,
+    @WorkingSessionParam session: WhatsappSession,
     @Param('id') id: string,
     @Body() request: ParticipantsRequest,
   ) {
@@ -192,12 +495,15 @@ export class GroupsController {
   }
 
   @Post(':id/participants/remove')
+  @HttpCode(HttpStatus.OK)
   @SessionApiParam
+  @GroupIdApiParam
+  @CheckPolicies(CanSession(Action.Send, FromParam('session')))
   @ApiOperation({
-    summary: 'Removes a list of participants by ID to the group.',
+    summary: 'Remove participants',
   })
   removeParticipants(
-    @SessionParam session: WhatsappSession,
+    @WorkingSessionParam session: WhatsappSession,
     @Param('id') id: string,
     @Body() request: ParticipantsRequest,
   ) {
@@ -205,10 +511,13 @@ export class GroupsController {
   }
 
   @Post(':id/admin/promote')
+  @HttpCode(HttpStatus.OK)
   @SessionApiParam
+  @GroupIdApiParam
+  @CheckPolicies(CanSession(Action.Send, FromParam('session')))
   @ApiOperation({ summary: 'Promote participants to admin users.' })
   promoteToAdmin(
-    @SessionParam session: WhatsappSession,
+    @WorkingSessionParam session: WhatsappSession,
     @Param('id') id: string,
     @Body() request: ParticipantsRequest,
   ) {
@@ -216,10 +525,13 @@ export class GroupsController {
   }
 
   @Post(':id/admin/demote')
+  @HttpCode(HttpStatus.OK)
   @SessionApiParam
-  @ApiOperation({ summary: 'Demotes participants by to regular users.' })
+  @GroupIdApiParam
+  @CheckPolicies(CanSession(Action.Send, FromParam('session')))
+  @ApiOperation({ summary: 'Demotes participants to regular users.' })
   demoteToAdmin(
-    @SessionParam session: WhatsappSession,
+    @WorkingSessionParam session: WhatsappSession,
     @Param('id') id: string,
     @Body() request: ParticipantsRequest,
   ) {

src/api/health.controller.ts

@@ -1,18 +1,28 @@
-import { Controller, Get } from '@nestjs/common';
-import { ApiOperation, ApiTags } from '@nestjs/swagger';
+import { Controller, Get, UseGuards } from '@nestjs/common';
+import { ApiOperation, ApiSecurity, ApiTags } from '@nestjs/swagger';
 import { HealthCheck } from '@nestjs/terminus';
 
 import { WAHAHealthCheckService } from '../core/abc/WAHAHealthCheckService';
+import { PoliciesGuard } from '@waha/core/auth/policies.guard';
+import { CheckPolicies } from '@waha/core/auth/policies.decorator';
+import { CanServer } from '@waha/core/auth/policies';
 
+import { Action } from '@waha/core/auth/casl.types';
+
+@ApiSecurity('api_key')
 @Controller('health')
-@ApiTags('other')
+@ApiTags('🔍 Observability')
+@UseGuards(PoliciesGuard)
+@CheckPolicies(CanServer(Action.Manage))
 export class HealthController {
   constructor(private wahaHealth: WAHAHealthCheckService) {}
 
   @Get()
   @HealthCheck()
   @ApiOperation({
-    summary: 'Check the health of the server, performing all health checks.',
+    summary: 'Check the health of the server',
+    description:
+      "Perform all health checks and return the server's health status.",
   })
   async check() {
     return this.wahaHealth.check();

src/api/helpers.ts

@@ -1,96 +0,0 @@
-import {
-  applyDecorators,
-  Injectable,
-  Param,
-  PipeTransform,
-} from '@nestjs/common';
-import {
-  ApiExtraModels,
-  ApiParam,
-  ApiResponse,
-  getSchemaPath,
-} from '@nestjs/swagger';
-
-import { SessionManager } from '../core/abc/manager.abc';
-import { WhatsappSession } from '../core/abc/session.abc';
-import { Base64File } from '../structures/files.dto';
-
-/**
- * Get session name and return Whatsapp session back (if exists)
- * use it as
- @Param('session', SessionPipe) session: WhatsappSession,
- */
-@Injectable()
-export class SessionPipe implements PipeTransform<WhatsappSession> {
-  constructor(private manager: SessionManager) {}
-
-  async transform(value: any) {
-    return this.manager.getSession(value);
-  }
-}
-
-/**
- * Decorator for a method that uses SessionPipe above
- */
-export const SessionApiParam = ApiParam({
-  name: 'session',
-  required: true,
-  type: 'string',
-  schema: {
-    default: 'default',
-  },
-  description: 'WhatsApp session name',
-});
-
-/**
- * Session param
- @SessionParam session: WhatsappSession,
- */
-export const SessionParam = Param('session', SessionPipe);
-
-export const ChatIdApiParam = ApiParam({
-  name: 'chatId',
-  required: true,
-  type: 'string',
-  description: 'Chat ID',
-  example: '123456789@c.us',
-});
-
-export const MessageIdApiParam = ApiParam({
-  name: 'messageId',
-  required: true,
-  type: 'string',
-  description: 'Message ID',
-  example: 'true_123456789@c.us_BAE6A33293978B16',
-});
-
-function getRefSchemaPaths(models) {
-  return models.map((model) => {
-    return { $ref: getSchemaPath(model) };
-  });
-}
-
-export function ApiFileAcceptHeader(...models) {
-  models = models.length ? models : [Base64File];
-  return applyDecorators(
-    // Add extra models, otherwise it'll give a error
-    // $ref not found
-    ApiExtraModels(...models),
-    ApiResponse({
-      status: 200,
-      content: {
-        'image/png': {
-          schema: {
-            type: 'string',
-            format: 'binary',
-          },
-        },
-        'application/json': {
-          schema: {
-            oneOf: getRefSchemaPaths(models),
-          },
-        },
-      },
-    }),
-  );
-}

src/api/labels.controller.ts

@@ -1,29 +1,135 @@
-import { Body, Controller, Get, Param, Put } from '@nestjs/common';
+import {
+  Body,
+  Controller,
+  Delete,
+  Get,
+  NotFoundException,
+  Param,
+  Post,
+  Put,
+  UnprocessableEntityException,
+  UseGuards,
+  UsePipes,
+  ValidationPipe,
+} from '@nestjs/common';
 import { ApiOperation, ApiSecurity, ApiTags } from '@nestjs/swagger';
-import { SessionApiParam, SessionParam } from '@waha/api/helpers';
 import { WhatsappSession } from '@waha/core/abc/session.abc';
-import { Label, LabelID, SetLabelsRequest } from '@waha/structures/labels.dto';
+import { ChatIdApiParam } from '@waha/nestjs/params/ChatIdApiParam';
+import {
+  SessionApiParam,
+  WorkingSessionParam,
+} from '@waha/nestjs/params/SessionApiParam';
+import {
+  Label,
+  LabelBody,
+  SetLabelsRequest,
+} from '@waha/structures/labels.dto';
+import * as lodash from 'lodash';
 
 import { SessionManager } from '../core/abc/manager.abc';
+import { PoliciesGuard } from '@waha/core/auth/policies.guard';
+import { CheckPolicies } from '@waha/core/auth/policies.decorator';
+import { CanSession, FromParam } from '@waha/core/auth/policies';
+
+import { Action } from '@waha/core/auth/casl.types';
 
 @ApiSecurity('api_key')
 @Controller('api/:session/labels')
-@ApiTags('labels')
+@ApiTags('🏷️ Labels')
+@UseGuards(PoliciesGuard)
 export class LabelsController {
   constructor(private manager: SessionManager) {}
 
   @Get('/')
   @SessionApiParam
+  @CheckPolicies(CanSession(Action.Read, FromParam('session')))
   @ApiOperation({ summary: 'Get all labels' })
-  getAll(@SessionParam session: WhatsappSession): Promise<Label[]> {
+  getAll(@WorkingSessionParam session: WhatsappSession): Promise<Label[]> {
     return session.getLabels();
   }
 
+  @Post('/')
+  @SessionApiParam
+  @CheckPolicies(CanSession(Action.Send, FromParam('session')))
+  @ApiOperation({ summary: 'Create a new label' })
+  @UsePipes(new ValidationPipe({ transform: true, whitelist: true }))
+  async create(
+    @WorkingSessionParam session: WhatsappSession,
+    @Body() body: LabelBody,
+  ): Promise<Label> {
+    const labelDto = body.toDTO();
+
+    const labels = await session.getLabels();
+    if (labels.length >= 20) {
+      throw new UnprocessableEntityException('Maximum 20 labels allowed');
+    }
+
+    const labelByName = lodash.find(labels, { name: labelDto.name });
+    if (labelByName) {
+      throw new UnprocessableEntityException(
+        `Label with '${labelByName.name}' already exists, id: ${labelByName.id}`,
+      );
+    }
+
+    return session.createLabel(labelDto);
+  }
+
+  @Put('/:labelId')
+  @SessionApiParam
+  @CheckPolicies(CanSession(Action.Send, FromParam('session')))
+  @ApiOperation({ summary: 'Update a label' })
+  @UsePipes(new ValidationPipe({ transform: true, whitelist: true }))
+  async update(
+    @WorkingSessionParam session: WhatsappSession,
+    @Param('labelId') labelId: string,
+    @Body() body: LabelBody,
+  ): Promise<Label> {
+    const label = await session.getLabel(labelId);
+    if (!label) {
+      throw new NotFoundException('Label not found');
+    }
+
+    const labelDto = body.toDTO();
+    const labels = await session.getLabels();
+
+    const labelByName = lodash.find(labels, { name: labelDto.name });
+    if (labelByName) {
+      throw new UnprocessableEntityException(
+        `Label with '${labelByName.name}' already exists, id: ${labelByName.id}`,
+      );
+    }
+
+    label.name = labelDto.name;
+    label.color = labelDto.color;
+    label.colorHex = Label.toHex(label.color);
+    await session.updateLabel(label);
+    return label;
+  }
+
+  @Delete('/:labelId')
+  @SessionApiParam
+  @CheckPolicies(CanSession(Action.Send, FromParam('session')))
+  @ApiOperation({ summary: 'Delete a label' })
+  @UsePipes(new ValidationPipe({ transform: true, whitelist: true }))
+  async delete(
+    @WorkingSessionParam session: WhatsappSession,
+    @Param('labelId') labelId: string,
+  ): Promise<any> {
+    const label = await session.getLabel(labelId);
+    if (!label) {
+      throw new NotFoundException('Label not found');
+    }
+    await session.deleteLabel(label);
+    return { result: true };
+  }
+
   @Get('/chats/:chatId')
   @SessionApiParam
+  @ChatIdApiParam
+  @CheckPolicies(CanSession(Action.Read, FromParam('session')))
   @ApiOperation({ summary: 'Get labels for the chat' })
   getChatLabels(
-    @SessionParam session: WhatsappSession,
+    @WorkingSessionParam session: WhatsappSession,
     @Param('chatId') chatId: string,
   ): Promise<Label[]> {
     return session.getChatLabels(chatId);
@@ -31,9 +137,11 @@ export class LabelsController {
 
   @Put('/chats/:chatId')
   @SessionApiParam
+  @ChatIdApiParam
+  @CheckPolicies(CanSession(Action.Send, FromParam('session')))
   @ApiOperation({ summary: 'Save labels for the chat' })
   putChatLabels(
-    @SessionParam session: WhatsappSession,
+    @WorkingSessionParam session: WhatsappSession,
     @Param('chatId') chatId: string,
     @Body() request: SetLabelsRequest,
   ) {
@@ -42,9 +150,10 @@ export class LabelsController {
 
   @Get('/:labelId/chats')
   @SessionApiParam
+  @CheckPolicies(CanSession(Action.Read, FromParam('session')))
   @ApiOperation({ summary: 'Get chats by label' })
   getChatsByLabel(
-    @SessionParam session: WhatsappSession,
+    @WorkingSessionParam session: WhatsappSession,
     @Param('labelId') labelId: string,
   ) {
     return session.getChatsByLabelId(labelId);

src/api/lids.controller.ts

@@ -0,0 +1,110 @@
+import {
+  Controller,
+  Get,
+  Param,
+  Query,
+  UnprocessableEntityException,
+  UseGuards,
+  UsePipes,
+  ValidationPipe,
+} from '@nestjs/common';
+import { ApiOperation, ApiSecurity, ApiTags } from '@nestjs/swagger';
+import { WhatsappSession } from '@waha/core/abc/session.abc';
+import {
+  SessionApiParam,
+  WorkingSessionParam,
+} from '@waha/nestjs/params/SessionApiParam';
+import { CountResponse } from '@waha/structures/base.dto';
+import {
+  LidsListQueryParams,
+  LidToPhoneNumber,
+} from '@waha/structures/lids.dto';
+import { PaginationParams, SortOrder } from '@waha/structures/pagination.dto';
+
+import { SessionManager } from '../core/abc/manager.abc';
+import { isLidUser } from '@waha/core/utils/jids';
+import { PoliciesGuard } from '@waha/core/auth/policies.guard';
+import { CheckPolicies } from '@waha/core/auth/policies.decorator';
+import { CanSession, FromParam } from '@waha/core/auth/policies';
+
+import { Action } from '@waha/core/auth/casl.types';
+
+@ApiSecurity('api_key')
+@Controller('api/:session/lids')
+@ApiTags('👤 Contacts')
+@UseGuards(PoliciesGuard)
+@CheckPolicies(CanSession(Action.Read, FromParam('session')))
+export class LidsController {
+  constructor(private manager: SessionManager) {}
+
+  @Get('/')
+  @SessionApiParam
+  @ApiOperation({ summary: 'Get all known lids to phone number mapping' })
+  @UsePipes(new ValidationPipe({ transform: true, whitelist: true }))
+  async getAll(
+    @WorkingSessionParam session: WhatsappSession,
+    @Query() params: LidsListQueryParams,
+  ): Promise<Array<LidToPhoneNumber>> {
+    // Always lid
+    const pagination: PaginationParams = params;
+    pagination.sortBy = 'lid';
+    pagination.sortOrder = SortOrder.ASC;
+    const lids = await session.getAllLids(pagination);
+    return lids;
+  }
+
+  @Get('/count')
+  @SessionApiParam
+  @ApiOperation({ summary: 'Get the number of known lids' })
+  @UsePipes(new ValidationPipe({ transform: true, whitelist: true }))
+  async getLidsCount(
+    @WorkingSessionParam session: WhatsappSession,
+  ): Promise<CountResponse> {
+    const count = await session.getLidsCount();
+    return {
+      count: count,
+    };
+  }
+
+  @Get('/:lid')
+  @SessionApiParam
+  @ApiOperation({ summary: 'Get phone number by lid' })
+  @UsePipes(new ValidationPipe({ transform: true, whitelist: true }))
+  async findPNByLid(
+    @WorkingSessionParam session: WhatsappSession,
+    @Param('lid') lid: string,
+  ): Promise<LidToPhoneNumber> {
+    if (!lid.includes('@')) {
+      lid = lid + '@lid';
+    }
+
+    if (!isLidUser(lid)) {
+      throw new UnprocessableEntityException(
+        'Invalid LID - it must end with @lid',
+      );
+    }
+    const result = await session.findPNByLid(lid);
+    result.pn = result.pn || null;
+    return result;
+  }
+
+  @Get('/pn/:phoneNumber')
+  @SessionApiParam
+  @ApiOperation({ summary: 'Get lid by phone number (chat id)' })
+  @UsePipes(new ValidationPipe({ transform: true, whitelist: true }))
+  async findLIDByPhoneNumber(
+    @WorkingSessionParam session: WhatsappSession,
+    @Param('phoneNumber') phoneNumber: string,
+  ): Promise<LidToPhoneNumber> {
+    if (isLidUser(phoneNumber)) {
+      return {
+        lid: phoneNumber,
+        pn: null,
+      };
+    }
+
+    const result = await session.findLIDByPhoneNumber(phoneNumber);
+    result.lid = result.lid || null;
+    return result;
+  }
+}

src/api/media.controller.ts

@@ -0,0 +1,91 @@
+import {
+  Body,
+  Controller,
+  Post,
+  UnprocessableEntityException,
+  UseGuards,
+  UseInterceptors,
+} from '@nestjs/common';
+import { ApiOperation, ApiSecurity, ApiTags } from '@nestjs/swagger';
+import { SessionManager } from '@waha/core/abc/manager.abc';
+import { WAMimeType } from '@waha/core/media/WAMimeType';
+import { ApiFileAcceptHeader } from '@waha/nestjs/ApiFileAcceptHeader';
+import {
+  SessionApiParam,
+  WorkingSessionParam,
+} from '@waha/nestjs/params/SessionApiParam';
+import {
+  FileDTO,
+  VideoFileDTO,
+  VoiceFileDTO,
+} from '@waha/structures/media.dto';
+
+import { WhatsappSession } from '../core/abc/session.abc';
+import { BufferResponseInterceptor } from '../nestjs/BufferResponseInterceptor';
+import { PoliciesGuard } from '@waha/core/auth/policies.guard';
+import { CheckPolicies } from '@waha/core/auth/policies.decorator';
+import { CanSession, FromParam } from '@waha/core/auth/policies';
+
+import { Action } from '@waha/core/auth/casl.types';
+
+@ApiSecurity('api_key')
+@Controller('api/:session/media')
+@ApiTags('🖼️ Media')
+@UseGuards(PoliciesGuard)
+@CheckPolicies(CanSession(Action.Read, FromParam('session')))
+class MediaController {
+  constructor(private manager: SessionManager) {}
+
+  @Post('convert/voice')
+  @ApiOperation({
+    summary: 'Convert voice to WhatsApp format (opus)',
+  })
+  @SessionApiParam
+  @UseInterceptors(
+    new BufferResponseInterceptor(WAMimeType.VOICE, 'output.opus'),
+  )
+  @ApiFileAcceptHeader(WAMimeType.VOICE)
+  async convertVoice(
+    @WorkingSessionParam session: WhatsappSession,
+    @Body() file: VoiceFileDTO,
+  ): Promise<Buffer> {
+    const data = await this.buffer(session, file);
+    const content = await session.mediaConverter.voice(data);
+    return content;
+  }
+
+  @Post('convert/video')
+  @ApiOperation({
+    summary: 'Convert video to WhatsApp format (mp4)',
+  })
+  @SessionApiParam
+  @UseInterceptors(
+    new BufferResponseInterceptor(WAMimeType.VIDEO, 'output.mp4'),
+  )
+  @ApiFileAcceptHeader(WAMimeType.VIDEO)
+  async convertVideo(
+    @WorkingSessionParam session: WhatsappSession,
+    @Body() file: VideoFileDTO,
+  ): Promise<Buffer> {
+    const data = await this.buffer(session, file);
+    const content = await session.mediaConverter.video(data);
+    return content;
+  }
+
+  private async buffer(
+    session: WhatsappSession,
+    file: FileDTO,
+  ): Promise<Buffer> {
+    if ('url' in file) {
+      return session.fetch(file.url);
+    } else if ('data' in file) {
+      return Buffer.from(file.data, 'base64');
+    } else {
+      throw new UnprocessableEntityException(
+        'Either "url" or "data" must be specified.',
+      );
+    }
+  }
+}
+
+export { MediaController };

src/api/ping.controller.ts

@@ -1,12 +1,15 @@
 import { Controller, Get } from '@nestjs/common';
-import { ApiOperation, ApiTags } from '@nestjs/swagger';
+import { ApiOperation, ApiSecurity, ApiTags } from '@nestjs/swagger';
 import { PingResponse } from '@waha/structures/ping.dto';
 
 @Controller('ping')
-@ApiTags('other')
+@ApiTags('🔍 Observability')
 export class PingController {
   @Get()
-  @ApiOperation({ summary: 'Ping the server, perform no operations.' })
+  @ApiOperation({
+    summary: 'Ping the server',
+    description: 'Check if the server is alive and responding to requests.',
+  })
   ping(): PingResponse {
     return { message: 'pong' };
   }

src/api/presence.controller.ts

@@ -5,8 +5,14 @@ import {
   Get,
   Param,
   Post,
+  UseGuards,
 } from '@nestjs/common';
 import { ApiOperation, ApiSecurity, ApiTags } from '@nestjs/swagger';
+import { ChatIdApiParam } from '@waha/nestjs/params/ChatIdApiParam';
+import {
+  SessionApiParam,
+  WorkingSessionParam,
+} from '@waha/nestjs/params/SessionApiParam';
 
 import { SessionManager } from '../core/abc/manager.abc';
 import { WhatsappSession } from '../core/abc/session.abc';
@@ -15,19 +21,25 @@ import {
   WAHAChatPresences,
   WAHASessionPresence,
 } from '../structures/presence.dto';
-import { SessionApiParam, SessionParam } from './helpers';
+import { PoliciesGuard } from '@waha/core/auth/policies.guard';
+import { CheckPolicies } from '@waha/core/auth/policies.decorator';
+import { CanSession, FromParam } from '@waha/core/auth/policies';
+
+import { Action } from '@waha/core/auth/casl.types';
 
 @ApiSecurity('api_key')
 @Controller('api/:session/presence')
-@ApiTags('presence')
+@ApiTags('✅ Presence')
+@UseGuards(PoliciesGuard)
 export class PresenceController {
   constructor(private manager: SessionManager) {}
 
   @Post('')
   @SessionApiParam
+  @CheckPolicies(CanSession(Action.Send, FromParam('session')))
   @ApiOperation({ summary: 'Set session presence' })
   setPresence(
-    @SessionParam session: WhatsappSession,
+    @WorkingSessionParam session: WhatsappSession,
     @Body() request: WAHASessionPresence,
   ) {
     // Validate request
@@ -55,21 +67,24 @@ export class PresenceController {
 
   @Get('')
   @SessionApiParam
+  @CheckPolicies(CanSession(Action.Read, FromParam('session')))
   @ApiOperation({ summary: 'Get all subscribed presence information.' })
   getPresenceAll(
-    @SessionParam session: WhatsappSession,
+    @WorkingSessionParam session: WhatsappSession,
   ): Promise<WAHAChatPresences[]> {
     return session.getPresences();
   }
 
   @Get(':chatId')
   @SessionApiParam
+  @ChatIdApiParam
+  @CheckPolicies(CanSession(Action.Read, FromParam('session')))
   @ApiOperation({
     summary:
       "Get the presence for the chat id. If it hasn't been subscribed - it also subscribes to it.",
   })
   getPresence(
-    @SessionParam session: WhatsappSession,
+    @WorkingSessionParam session: WhatsappSession,
     @Param('chatId') chatId: string,
   ): Promise<WAHAChatPresences> {
     return session.getPresence(chatId);
@@ -77,11 +92,13 @@ export class PresenceController {
 
   @Post(':chatId/subscribe')
   @SessionApiParam
+  @ChatIdApiParam
+  @CheckPolicies(CanSession(Action.Send, FromParam('session')))
   @ApiOperation({
     summary: 'Subscribe to presence events for the chat.',
   })
   subscribe(
-    @SessionParam session: WhatsappSession,
+    @WorkingSessionParam session: WhatsappSession,
     @Param('chatId') chatId: string,
   ): Promise<void> {
     return session.subscribePresence(chatId);

src/api/profile.controller.ts

@@ -0,0 +1,106 @@
+import {
+  Body,
+  Controller,
+  Delete,
+  Get,
+  Put,
+  UnprocessableEntityException,
+  UseGuards,
+  UsePipes,
+} from '@nestjs/common';
+import { ApiOperation, ApiSecurity, ApiTags } from '@nestjs/swagger';
+import { SessionManager } from '@waha/core/abc/manager.abc';
+import { WhatsappSession } from '@waha/core/abc/session.abc';
+import {
+  SessionApiParam,
+  WorkingSessionParam,
+} from '@waha/nestjs/params/SessionApiParam';
+import { WAHAValidationPipe } from '@waha/nestjs/pipes/WAHAValidationPipe';
+import { Result } from '@waha/structures/base.dto';
+import {
+  MyProfile,
+  ProfileNameRequest,
+  ProfilePictureRequest,
+  ProfileStatusRequest,
+} from '@waha/structures/profile.dto';
+import { PoliciesGuard } from '@waha/core/auth/policies.guard';
+import { CheckPolicies } from '@waha/core/auth/policies.decorator';
+import { CanSession, FromParam } from '@waha/core/auth/policies';
+
+import { Action } from '@waha/core/auth/casl.types';
+
+@ApiSecurity('api_key')
+@Controller('api/:session/profile')
+@ApiTags('🆔 Profile')
+@UseGuards(PoliciesGuard)
+export class ProfileController {
+  constructor(private manager: SessionManager) {}
+
+  @Get('')
+  @SessionApiParam
+  @CheckPolicies(CanSession(Action.Read, FromParam('session')))
+  @ApiOperation({ summary: 'Get my profile' })
+  async getMyProfile(
+    @WorkingSessionParam session: WhatsappSession,
+  ): Promise<MyProfile> {
+    const me = session.getSessionMeInfo();
+    if (!me) {
+      throw new UnprocessableEntityException('No profile found');
+    }
+    const picture = await session.getContactProfilePicture(me.id, false);
+    return {
+      id: me.id,
+      name: me.pushName,
+      picture: picture || null,
+    };
+  }
+
+  @Put('/name')
+  @SessionApiParam
+  @CheckPolicies(CanSession(Action.Send, FromParam('session')))
+  @UsePipes(new WAHAValidationPipe())
+  @ApiOperation({ summary: 'Set my profile name' })
+  async setProfileName(
+    @WorkingSessionParam session: WhatsappSession,
+    @Body() request: ProfileNameRequest,
+  ): Promise<Result> {
+    const success = await session.setProfileName(request.name);
+    return { success: success ?? true };
+  }
+
+  @Put('/status')
+  @SessionApiParam
+  @CheckPolicies(CanSession(Action.Send, FromParam('session')))
+  @UsePipes(new WAHAValidationPipe())
+  @ApiOperation({ summary: 'Set profile status (About)' })
+  async setProfileStatus(
+    @WorkingSessionParam session: WhatsappSession,
+    @Body() request: ProfileStatusRequest,
+  ): Promise<Result> {
+    const success = await session.setProfileStatus(request.status);
+    return { success: success ?? true };
+  }
+
+  @Put('/picture')
+  @SessionApiParam
+  @CheckPolicies(CanSession(Action.Send, FromParam('session')))
+  @ApiOperation({ summary: 'Set profile picture' })
+  async setProfilePicture(
+    @WorkingSessionParam session: WhatsappSession,
+    @Body() request: ProfilePictureRequest,
+  ): Promise<Result> {
+    const success = await session.updateProfilePicture(request.file);
+    return { success: success ?? true };
+  }
+
+  @Delete('/picture')
+  @SessionApiParam
+  @CheckPolicies(CanSession(Action.Send, FromParam('session')))
+  @ApiOperation({ summary: 'Delete profile picture' })
+  async deleteProfilePicture(
+    @WorkingSessionParam session: WhatsappSession,
+  ): Promise<Result> {
+    const success = await session.updateProfilePicture(null);
+    return { success: success || true };
+  }
+}

src/api/screenshot.controller.ts

@@ -4,25 +4,37 @@ import {
   Query,
   Res,
   StreamableFile,
+  UseGuards,
   UseInterceptors,
 } from '@nestjs/common';
-import { ApiSecurity, ApiTags } from '@nestjs/swagger';
+import { ApiOperation, ApiSecurity, ApiTags } from '@nestjs/swagger';
+import { ApiFileAcceptHeader } from '@waha/nestjs/ApiFileAcceptHeader';
 import { Response } from 'express';
 
 import { SessionManager } from '../core/abc/manager.abc';
+import { BufferResponseInterceptor } from '../nestjs/BufferResponseInterceptor';
 import { SessionQuery } from '../structures/base.dto';
-import { BufferResponseInterceptor } from './BufferResponseInterceptor';
-import { ApiFileAcceptHeader } from './helpers';
+import { PoliciesGuard } from '@waha/core/auth/policies.guard';
+import { CheckPolicies } from '@waha/core/auth/policies.decorator';
+import { CanSession, FromQuery } from '@waha/core/auth/policies';
+
+import { Action } from '@waha/core/auth/casl.types';
 
 @ApiSecurity('api_key')
 @Controller('api')
-@ApiTags('screenshot')
+@ApiTags('📱 Pairing')
+@UseGuards(PoliciesGuard)
+@CheckPolicies(CanSession(Action.Control, FromQuery('session')))
 export class ScreenshotController {
   constructor(private manager: SessionManager) {}
 
   @Get('/screenshot')
-  @UseInterceptors(new BufferResponseInterceptor())
-  @ApiFileAcceptHeader()
+  @ApiOperation({
+    summary:
+      'Get a screenshot of the current WhatsApp session (**WEBJS/WPP** only)',
+  })
+  @UseInterceptors(new BufferResponseInterceptor('image/jpeg'))
+  @ApiFileAcceptHeader('image/jpeg')
   async screenshot(
     @Res({ passthrough: true }) res: Response,
     @Query() sessionQuery: SessionQuery,

src/api/server.controller.ts

@@ -0,0 +1,122 @@
+import * as process from 'node:process';
+
+import {
+  Body,
+  Controller,
+  Get,
+  Logger,
+  Post,
+  Query,
+  UseGuards,
+  UsePipes,
+} from '@nestjs/common';
+import { ApiOperation, ApiSecurity, ApiTags } from '@nestjs/swagger';
+import { WhatsappConfigService } from '@waha/config.service';
+import { WAHAValidationPipe } from '@waha/nestjs/pipes/WAHAValidationPipe';
+import { WAHAEnvironment } from '@waha/structures/environment.dto';
+import {
+  EnvironmentQuery,
+  ServerStatusResponse,
+  StopRequest,
+  StopResponse,
+} from '@waha/structures/server.dto';
+import { sleep } from '@waha/utils/promiseTimeout';
+import { VERSION } from '@waha/version';
+import * as lodash from 'lodash';
+import { PoliciesGuard } from '@waha/core/auth/policies.guard';
+import { CheckPolicies } from '@waha/core/auth/policies.decorator';
+import { CanServer } from '@waha/core/auth/policies';
+
+import { Action } from '@waha/core/auth/casl.types';
+
+@ApiSecurity('api_key')
+@Controller('api/server')
+@ApiTags('🔍 Observability')
+@UseGuards(PoliciesGuard)
+export class ServerController {
+  private logger: Logger;
+
+  constructor(private config: WhatsappConfigService) {
+    this.logger = new Logger('ServerController');
+  }
+
+  @Get('version')
+  @ApiOperation({ summary: 'Get the version of the server' })
+  @CheckPolicies(CanServer(Action.Retrieve))
+  get(): WAHAEnvironment {
+    return VERSION;
+  }
+
+  @Get('environment')
+  @ApiOperation({ summary: 'Get the server environment' })
+  @CheckPolicies(CanServer(Action.Manage))
+  environment(
+    @Query(new WAHAValidationPipe()) query: EnvironmentQuery,
+    // eslint-disable-next-line @typescript-eslint/ban-types
+  ): object {
+    let result = process.env;
+    if (!query.all) {
+      result = lodash.pickBy(result, (value, key) => {
+        return (
+          key.startsWith('WAHA_') ||
+          key.startsWith('WHATSAPP_') ||
+          key === 'DEBUG'
+        );
+      });
+    }
+    const map = new Map<string, string>();
+    // sort and set
+    Object.keys(result)
+      .sort()
+      .forEach((key) => {
+        map.set(key, result[key]);
+      });
+    return Object.fromEntries(map);
+  }
+
+  @Get('status')
+  @ApiOperation({ summary: 'Get the server status' })
+  @CheckPolicies(CanServer(Action.Retrieve))
+  async status(): Promise<ServerStatusResponse> {
+    const now = Date.now();
+    const uptime = Math.floor(process.uptime() * 1000);
+    const startTimestamp = now - uptime;
+    return {
+      startTimestamp: startTimestamp,
+      uptime: uptime,
+      worker: {
+        id: this.config.workerId,
+      },
+    };
+  }
+
+  @Post('stop')
+  @ApiOperation({
+    summary: 'Stop (and restart) the server',
+    description:
+      "If you're using docker, after calling this endpoint Docker will start a new container, " +
+      'so you can use this endpoint to restart the server',
+  })
+  @CheckPolicies(CanServer(Action.Manage))
+  @UsePipes(new WAHAValidationPipe())
+  async stop(@Body() request: StopRequest): Promise<StopResponse> {
+    const timeout = 1_000;
+    if (request.force) {
+      this.logger.log(`Force stopping the server in ${timeout}ms`);
+      setTimeout(() => {
+        this.logger.log('Force stopping the server');
+        process.kill(process.pid, 'SIGKILL');
+        process.exit(0);
+      }, timeout);
+    } else {
+      this.logger.log(`Gracefully stopping the server in ${timeout}ms`);
+      setTimeout(async () => {
+        this.logger.log('Gracefully closing the application...');
+        process.kill(process.pid, 'SIGTERM');
+        await sleep(10_000);
+        process.exit(0);
+      }, timeout);
+    }
+    return { stopping: true };
+  }
+}

src/api/server.debug.controller.ts

@@ -0,0 +1,142 @@
+import * as inspector from 'node:inspector';
+import * as v8 from 'node:v8';
+import { Readable } from 'node:stream';
+
+import {
+  Controller,
+  Get,
+  Logger,
+  NotFoundException,
+  Query,
+  StreamableFile,
+  UseGuards,
+  UsePipes,
+} from '@nestjs/common';
+import { ApiOperation, ApiSecurity, ApiTags } from '@nestjs/swagger';
+import { WhatsappConfigService } from '@waha/config.service';
+import { SessionManager } from '@waha/core/abc/manager.abc';
+import { WhatsappSession } from '@waha/core/abc/session.abc';
+import {
+  SessionApiParam,
+  WorkingSessionParam,
+} from '@waha/nestjs/params/SessionApiParam';
+import { WAHAValidationPipe } from '@waha/nestjs/pipes/WAHAValidationPipe';
+import {
+  BrowserTraceQuery,
+  CpuProfileQuery,
+} from '@waha/structures/server.debug.dto';
+import { createReadStream } from 'fs';
+import { PoliciesGuard } from '@waha/core/auth/policies.guard';
+import { CheckPolicies } from '@waha/core/auth/policies.decorator';
+import { CanServer } from '@waha/core/auth/policies';
+
+import { Action } from '@waha/core/auth/casl.types';
+
+@ApiSecurity('api_key')
+@Controller('api/server/debug')
+@ApiTags('🔍 Observability')
+@UseGuards(PoliciesGuard)
+@CheckPolicies(CanServer(Action.Manage))
+export class ServerDebugController {
+  private logger: Logger;
+  private readonly enabled: boolean;
+
+  constructor(
+    private config: WhatsappConfigService,
+    private manager: SessionManager,
+  ) {
+    this.logger = new Logger('ServerDebugController');
+    this.enabled = this.config.debugModeEnabled;
+  }
+
+  @Get('cpu')
+  @ApiOperation({
+    summary: 'Collect and return a CPU profile for the current nodejs process',
+    description: 'Uses the Node.js inspector profiler to capture a .cpuprofile',
+  })
+  @UsePipes(new WAHAValidationPipe())
+  async cpuProfile(@Query() query: CpuProfileQuery) {
+    if (!this.enabled) {
+      throw new NotFoundException('WAHA_DEBUG_MODE is disabled');
+    }
+    const { seconds } = query;
+    this.logger.log(`Collecting CPU profile for ${seconds}s...`);
+
+    const session = new inspector.Session();
+    session.connect();
+
+    const profile = await new Promise<inspector.Profiler.Profile>(
+      (resolve, reject) => {
+        session.post('Profiler.enable', (enableError) => {
+          if (enableError) {
+            session.disconnect();
+            return reject(enableError);
+          }
+          session.post('Profiler.start', (startError) => {
+            if (startError) {
+              session.disconnect();
+              return reject(startError);
+            }
+            setTimeout(() => {
+              session.post('Profiler.stop', (stopError, params) => {
+                session.disconnect();
+                if (stopError) {
+                  return reject(stopError);
+                }
+                resolve(params.profile);
+              });
+            }, seconds * 1000);
+          });
+        });
+      },
+    );
+
+    const filename = `CPU.${Date.now()}.${process.pid}.cpuprofile`;
+    const stream = Readable.from([JSON.stringify(profile)]);
+    return new StreamableFile(stream, {
+      type: 'application/json',
+      disposition: `attachment; filename=${filename}`,
+    });
+  }
+
+  @Get('heapsnapshot')
+  @ApiOperation({
+    summary: 'Return a heapsnapshot for the current nodejs process',
+    description: "Return a heapsnapshot of the server's memory",
+  })
+  async heapsnapshot() {
+    if (!this.enabled) {
+      throw new NotFoundException('WAHA_DEBUG_MODE is disabled');
+    }
+    this.logger.log('Creating a heap snapshot...');
+    const heap = v8.getHeapSnapshot();
+    const fileName = `${Date.now()}.heapsnapshot`;
+    return new StreamableFile(heap, {
+      type: 'application/octet-stream',
+      disposition: `attachment; filename=${fileName}`,
+    });
+  }
+
+  @Get('browser/trace/:session')
+  @ApiOperation({
+    summary: 'Collect and get a trace.json for Chrome DevTools ',
+    description: 'Uses https://pptr.dev/api/puppeteer.tracing',
+  })
+  @SessionApiParam
+  @UsePipes(new WAHAValidationPipe())
+  async browserTrace(
+    @WorkingSessionParam session: WhatsappSession,
+    @Query() query: BrowserTraceQuery,
+  ) {
+    if (!this.enabled) {
+      throw new NotFoundException('WAHA_DEBUG_MODE is disabled');
+    }
+    const filepath = await session.browserTrace(query);
+    const stream = createReadStream(filepath);
+    const filename = `trace - ${session.name} - ${new Date()}.json`;
+    return new StreamableFile(stream, {
+      type: 'application/octet-stream',
+      disposition: `attachment; filename=${filename}`,
+    });
+  }
+}

src/api/sessions.controller.ts

@@ -3,93 +3,289 @@ import {
   Controller,
   Delete,
   Get,
-  NotFoundException,
   Param,
   Post,
+  Put,
   Query,
+  Req,
+  UseGuards,
+  UsePipes,
 } from '@nestjs/common';
+import { UnprocessableEntityException } from '@nestjs/common/exceptions/unprocessable-entity.exception';
 import {
-  ApiExtraModels,
+  ApiBody,
+  ApiOAuth2,
   ApiOperation,
   ApiSecurity,
   ApiTags,
 } from '@nestjs/swagger';
+import {
+  SessionApiParam,
+  SessionParam,
+} from '@waha/nestjs/params/SessionApiParam';
+import { WAHAValidationPipe } from '@waha/nestjs/pipes/WAHAValidationPipe';
+import {
+  SessionLogoutDeprecatedRequest,
+  SessionStartDeprecatedRequest,
+  SessionStopDeprecatedRequest,
+} from '@waha/structures/sessions.deprecated.dto';
 
-import { SessionManager } from '../core/abc/manager.abc';
 import { WhatsappSession } from '../core/abc/session.abc';
-import { parseBool } from '../helpers';
 import {
   ListSessionsQuery,
   MeInfo,
+  MessageCappingData,
+  ReachoutTimelockData,
+  SessionCreateRequest,
   SessionDTO,
+  SessionExpand,
   SessionInfo,
+  SessionInfoQuery,
   SessionLogoutRequest,
-  SessionStartRequest,
-  SessionStopRequest,
+  SessionUpdateRequest,
 } from '../structures/sessions.dto';
-import { SessionApiParam, SessionParam } from './helpers';
+import { SessionExamples } from './sessions.examples';
+import { FilterSessions } from '../core/auth/casl.ability';
+import { CheckPolicies } from '../core/auth/policies.decorator';
+import { PoliciesGuard } from '../core/auth/policies.guard';
+import { CanSession, FromBody, FromParam } from '../core/auth/policies';
+import { Action } from '@waha/core/auth/casl.types';
+import { SessionService } from '@waha/core/services/SessionService';
 
 @ApiSecurity('api_key')
 @Controller('api/sessions')
-@ApiTags('sessions')
+@ApiTags('🖥️ Sessions')
+@UseGuards(PoliciesGuard)
 class SessionsController {
-  constructor(private manager: SessionManager) {}
-
-  @Post('/start/')
-  async start(@Body() request: SessionStartRequest): Promise<SessionDTO> {
-    const result = await this.manager.start(request);
-    await this.manager.sessionConfigRepository.save(
-      request.name,
-      request.config || null,
-    );
-    return result;
-  }
-
-  @Post('/stop/')
-  @ApiOperation({ summary: 'Stop session' })
-  async stop(@Body() request: SessionStopRequest): Promise<void> {
-    if (request.logout) {
-      await this.manager.logout(request);
-    } else {
-      await this.manager.stop(request);
-    }
-    return;
-  }
-
-  @Post('/logout/')
-  @ApiOperation({ summary: 'Logout from session.' })
-  clean(@Body() request: SessionLogoutRequest): Promise<void> {
-    return this.manager.logout(request);
-  }
+  constructor(private readonly sessionService: SessionService) {}
 
   @Get('/')
-  list(@Query() query: ListSessionsQuery): Promise<SessionInfo[]> {
-    const all = parseBool(query.all);
-    return this.manager.getSessions(all);
+  @ApiOperation({ summary: 'List all sessions' })
+  @CheckPolicies(CanSession(Action.List))
+  @ApiOAuth2(['read:items'])
+  async list(
+    @Query(new WAHAValidationPipe()) query: ListSessionsQuery,
+    @Req() req,
+  ): Promise<SessionInfo[]> {
+    let sessions = await this.sessionService.getSessions(query.all);
+    if (!req.user?.isAdmin) {
+      sessions = FilterSessions(req.ability, Action.Retrieve, sessions);
+    }
+    if (query.expand?.includes(SessionExpand.apps)) {
+      await this.sessionService.expandSessionApps(sessions);
+    }
+    return sessions;
   }
 
   @Get('/:session')
-  async get(@Param('session') name: string): Promise<SessionInfo> {
-    const session = this.manager.getSessionInfo(name);
-    if (session === null) {
-      throw new NotFoundException('Session not found');
+  @ApiOperation({ summary: 'Get session information' })
+  @SessionApiParam
+  @CheckPolicies(CanSession(Action.Read, FromParam('session')))
+  @UsePipes(new WAHAValidationPipe())
+  async get(
+    @Param('session') name: string,
+    @Query() query: SessionInfoQuery,
+  ): Promise<SessionInfo> {
+    const session = await this.sessionService.getSession(name);
+    if (query.expand?.includes(SessionExpand.apps)) {
+      await this.sessionService.expandSessionApps([session]);
     }
     return session;
   }
-}
 
-@ApiSecurity('api_key')
-@Controller('api/sessions/:session')
-@ApiTags('sessions')
-class SessionController {
-  constructor(private manager: SessionManager) {}
-
-  @Get('me')
+  @Get(':session/me')
   @SessionApiParam
   @ApiOperation({ summary: 'Get information about the authenticated account' })
+  @CheckPolicies(CanSession(Action.Read, FromParam('session')))
   getMe(@SessionParam session: WhatsappSession): MeInfo | null {
-    return session.getSessionMeInfo();
+    return this.sessionService.getSessionMe(session);
+  }
+
+  @Get(':session/capping')
+  @SessionApiParam
+  @ApiOperation({
+    summary: 'Fetch the account new-chat message capping (per-cycle quota)',
+    description:
+      'Fetch a fresh new-chat message capping (quota) state from WhatsApp. ' +
+      'The same value is also available under me.messageCapping in the session ' +
+      'info, and changes are pushed through the session.status event.',
+  })
+  @CheckPolicies(CanSession(Action.Read, FromParam('session')))
+  fetchMessageCapping(
+    @SessionParam session: WhatsappSession,
+  ): Promise<MessageCappingData> {
+    return session.fetchMessageCapping();
+  }
+
+  @Get(':session/timelock')
+  @SessionApiParam
+  @ApiOperation({
+    summary: 'Fetch the account reachout timelock state',
+    description:
+      'Fetch a fresh reachout timelock state from WhatsApp - the restriction ' +
+      'behind "server returned error 463" when messaging new contacts. ' +
+      'The same value is also available under me.reachoutTimelock in the session ' +
+      'info, and changes are pushed through the session.status event.',
+  })
+  @CheckPolicies(CanSession(Action.Read, FromParam('session')))
+  fetchReachoutTimelock(
+    @SessionParam session: WhatsappSession,
+  ): Promise<ReachoutTimelockData> {
+    return session.fetchReachoutTimelock();
+  }
+
+  @Post('')
+  @ApiOperation({
+    summary: 'Create a session',
+    description:
+      'Create session a new session (and start it at the same time if required).',
+  })
+  @ApiBody({ type: SessionCreateRequest, examples: SessionExamples })
+  @CheckPolicies(CanSession(Action.Create))
+  @UsePipes(new WAHAValidationPipe())
+  async create(@Body() request: SessionCreateRequest): Promise<SessionDTO> {
+    return this.sessionService.createSession(request);
+  }
+
+  @Put(':session')
+  @ApiOperation({ summary: 'Update a session' })
+  @SessionApiParam
+  @ApiBody({ type: SessionUpdateRequest, examples: SessionExamples })
+  @CheckPolicies(CanSession(Action.Setting, FromParam('session')))
+  @UsePipes(new WAHAValidationPipe({ forbidNonWhitelisted: false }))
+  async update(
+    @Param('session') name: string,
+    @Body() request: SessionUpdateRequest,
+  ): Promise<SessionDTO> {
+    return this.sessionService.updateSession(name, request);
+  }
+
+  @Delete(':session')
+  @SessionApiParam
+  @ApiOperation({
+    summary: 'Delete the session',
+    description:
+      'Delete the session with the given name. Stop and logout as well. Idempotent operation.',
+  })
+  @CheckPolicies(CanSession(Action.Delete, FromParam('session')))
+  @UsePipes(new WAHAValidationPipe())
+  async delete(@Param('session') name: string): Promise<void> {
+    return this.sessionService.deleteSession(name);
+  }
+
+  @Post(':session/start')
+  @SessionApiParam
+  @ApiOperation({
+    summary: 'Start the session',
+    description:
+      'Start the session with the given name. The session must exist. Idempotent operation.',
+  })
+  @CheckPolicies(CanSession(Action.Control, FromParam('session')))
+  @UsePipes(new WAHAValidationPipe())
+  async start(@Param('session') name: string): Promise<SessionDTO> {
+    return this.sessionService.startSession(name);
+  }
+
+  @Post(':session/stop')
+  @SessionApiParam
+  @ApiOperation({
+    summary: 'Stop the session',
+    description: 'Stop the session with the given name. Idempotent operation.',
+  })
+  @CheckPolicies(CanSession(Action.Control, FromParam('session')))
+  @UsePipes(new WAHAValidationPipe())
+  async stop(@Param('session') name: string): Promise<SessionDTO> {
+    return this.sessionService.stopSession(name);
+  }
+
+  @Post(':session/logout')
+  @SessionApiParam
+  @ApiOperation({
+    summary: 'Logout from the session',
+    description: 'Logout the session, restart a session if it was not STOPPED',
+  })
+  @ApiBody({ type: SessionLogoutRequest, required: false })
+  @CheckPolicies(CanSession(Action.Control, FromParam('session')))
+  @UsePipes(new WAHAValidationPipe())
+  async logout(
+    @Param('session') name: string,
+    @Body() request?: SessionLogoutRequest,
+  ): Promise<SessionDTO> {
+    return this.sessionService.logoutSession(name, request);
+  }
+
+  @Post(':session/restart')
+  @SessionApiParam
+  @ApiOperation({
+    summary: 'Restart the session',
+    description: 'Restart the session with the given name.',
+  })
+  @CheckPolicies(CanSession(Action.Control, FromParam('session')))
+  @UsePipes(new WAHAValidationPipe())
+  async restart(@Param('session') name: string): Promise<SessionDTO> {
+    return this.sessionService.restartSession(name);
+  }
+
+  @Post('/start/')
+  @ApiOperation({
+    summary: 'Upsert and Start session',
+    description:
+      'Create session (if not exists) or update a config (if exists) and start it.',
+    deprecated: true,
+  })
+  @CheckPolicies(CanSession(Action.Control, FromBody('name')))
+  async DEPRACATED_start(
+    @Body() request: SessionStartDeprecatedRequest,
+  ): Promise<SessionDTO> {
+    if (!request.name) {
+      throw new UnprocessableEntityException('Session name is required');
+    }
+    if (this.sessionService.isSessionRunning(request.name)) {
+      throw new UnprocessableEntityException(
+        `Session '${request.name}' is already started.`,
+      );
+    }
+    return this.sessionService.upsertAndStartSession(
+      request.name,
+      request.config,
+    );
+  }
+
+  @Post('/stop/')
+  @ApiOperation({
+    summary: 'Stop (and Logout if asked) session',
+    description: 'Stop session and Logout by default.',
+    deprecated: true,
+  })
+  @CheckPolicies(CanSession(Action.Control, FromBody('name')))
+  async DEPRECATED_stop(
+    @Body() request: SessionStopDeprecatedRequest,
+  ): Promise<void> {
+    if (!request.name) {
+      throw new UnprocessableEntityException('Session name is required');
+    }
+    if (request.logout) {
+      await this.sessionService.deleteSession(request.name);
+    } else {
+      await this.sessionService.stopSession(request.name);
+    }
+  }
+
+  @Post('/logout/')
+  @ApiOperation({
+    summary: 'Logout and Delete session.',
+    description: 'Stop, Logout and Delete session.',
+    deprecated: true,
+  })
+  @CheckPolicies(CanSession(Action.Control, FromBody('name')))
+  async DEPRECATED_logout(
+    @Body() request: SessionLogoutDeprecatedRequest,
+  ): Promise<void> {
+    if (!request.name) {
+      throw new UnprocessableEntityException('Session name is required');
+    }
+    await this.sessionService.deleteSession(request.name);
   }
 }
 
-export { SessionController, SessionsController };
+export { SessionsController };

src/api/sessions.examples.ts

@@ -0,0 +1,102 @@
+import { AppName } from '@waha/apps/app_sdk/apps/apps';
+
+export const SessionExamples = {
+  basic: {
+    summary: 'Basic Session',
+    value: {
+      name: 'default',
+    },
+  },
+  withWebhooks: {
+    summary: 'Session Webhooks',
+    value: {
+      name: 'default',
+      config: {
+        webhooks: [
+          {
+            url: 'https://example.com/webhooks/waha',
+            events: ['message', 'session.status'],
+            hmac: {
+              key: 'super-secret',
+            },
+            retries: {
+              delaySeconds: 2,
+              attempts: 5,
+              policy: 'linear',
+            },
+            customHeaders: [
+              {
+                name: 'X-Request-ID',
+                value: '123',
+              },
+            ],
+          },
+        ],
+      },
+    },
+  },
+  withApps: {
+    summary: 'Session Apps',
+    value: {
+      name: 'default',
+      apps: [
+        {
+          app: AppName.calls,
+          id: 'app_unique_id',
+          session: '',
+          config: {
+            dm: {
+              reject: true,
+              message:
+                "📞❌ We don't take calls right now.\n🎤 Please send a voice message or 📝 text — we'll reply ASAP!",
+            },
+            group: {
+              reject: true,
+              message:
+                "📞❌ We don't take calls right now.\n🎤 Please send a voice message or 📝 text — we'll reply ASAP!",
+            },
+          },
+        },
+      ],
+      start: true,
+    },
+  },
+  full: {
+    summary: 'Full Session Example',
+    value: {
+      name: 'default',
+      start: true,
+      config: {
+        metadata: {
+          'user.id': '123',
+        },
+        debug: true,
+        webhooks: [
+          {
+            url: 'https://example.com/webhooks/waha',
+            events: ['message', 'session.status'],
+            hmac: {
+              key: 'super-secret',
+            },
+          },
+        ],
+      },
+      apps: [
+        {
+          app: AppName.calls,
+          enabled: true,
+          config: {
+            dm: {
+              reject: true,
+              message:
+                "📞❌ We don't take calls right now.\n🎤 Please send a voice message or 📝 text — we'll reply ASAP!",
+            },
+            group: {
+              reject: true,
+            },
+          },
+        },
+      ],
+    },
+  },
+};

src/api/status.controller.ts

@@ -1,13 +1,10 @@
-import {
-  Body,
-  Controller,
-  Delete,
-  Get,
-  Param,
-  Post,
-  Query,
-} from '@nestjs/common';
+import { Body, Controller, Get, Post, UseGuards } from '@nestjs/common';
 import { ApiOperation, ApiSecurity, ApiTags } from '@nestjs/swagger';
+import {
+  SessionApiParam,
+  WorkingSessionParam,
+} from '@waha/nestjs/params/SessionApiParam';
+import { NewMessageIDResponse } from '@waha/structures/chatting.dto';
 
 import { SessionManager } from '../core/abc/manager.abc';
 import { WhatsappSession } from '../core/abc/session.abc';
@@ -18,19 +15,25 @@ import {
   VideoStatus,
   VoiceStatus,
 } from '../structures/status.dto';
-import { SessionApiParam, SessionParam } from './helpers';
+import { PoliciesGuard } from '@waha/core/auth/policies.guard';
+import { CheckPolicies } from '@waha/core/auth/policies.decorator';
+import { CanSession, FromParam } from '@waha/core/auth/policies';
+
+import { Action } from '@waha/core/auth/casl.types';
 
 @ApiSecurity('api_key')
 @Controller('api/:session/status')
-@ApiTags('status')
+@ApiTags('🟢 Status')
+@UseGuards(PoliciesGuard)
 class StatusController {
   constructor(private manager: SessionManager) {}
 
   @Post('text')
   @SessionApiParam
-  @ApiOperation({ summary: 'Send text status.' })
+  @CheckPolicies(CanSession(Action.Send, FromParam('session')))
+  @ApiOperation({ summary: 'Send text status' })
   sendTextStatus(
-    @SessionParam session: WhatsappSession,
+    @WorkingSessionParam session: WhatsappSession,
     @Body() status: TextStatus,
   ) {
     return session.sendTextStatus(status);
@@ -38,9 +41,10 @@ class StatusController {
 
   @Post('image')
   @SessionApiParam
-  @ApiOperation({ summary: 'Send image status.' })
+  @CheckPolicies(CanSession(Action.Send, FromParam('session')))
+  @ApiOperation({ summary: 'Send image status' })
   sendImageStatus(
-    @SessionParam session: WhatsappSession,
+    @WorkingSessionParam session: WhatsappSession,
     @Body() status: ImageStatus,
   ) {
     return session.sendImageStatus(status);
@@ -48,9 +52,10 @@ class StatusController {
 
   @Post('voice')
   @SessionApiParam
-  @ApiOperation({ summary: 'Send voice status.' })
+  @CheckPolicies(CanSession(Action.Send, FromParam('session')))
+  @ApiOperation({ summary: 'Send voice status' })
   sendVoiceStatus(
-    @SessionParam session: WhatsappSession,
+    @WorkingSessionParam session: WhatsappSession,
     @Body() status: VoiceStatus,
   ) {
     return session.sendVoiceStatus(status);
@@ -58,9 +63,10 @@ class StatusController {
 
   @Post('video')
   @SessionApiParam
-  @ApiOperation({ summary: 'Send video status.' })
+  @CheckPolicies(CanSession(Action.Send, FromParam('session')))
+  @ApiOperation({ summary: 'Send video status' })
   sendVideoStatus(
-    @SessionParam session: WhatsappSession,
+    @WorkingSessionParam session: WhatsappSession,
     @Body() status: VideoStatus,
   ) {
     return session.sendVideoStatus(status);
@@ -68,13 +74,27 @@ class StatusController {
 
   @Post('delete')
   @SessionApiParam
-  @ApiOperation({ summary: 'DELETE sent status.' })
+  @CheckPolicies(CanSession(Action.Send, FromParam('session')))
+  @ApiOperation({ summary: 'DELETE sent status' })
   deleteStatus(
-    @SessionParam session: WhatsappSession,
+    @WorkingSessionParam session: WhatsappSession,
     @Body() status: DeleteStatusRequest,
   ) {
     return session.deleteStatus(status);
   }
+
+  @Get('new-message-id')
+  @SessionApiParam
+  @CheckPolicies(CanSession(Action.Send, FromParam('session')))
+  @ApiOperation({
+    summary: 'Generate message ID you can use to batch contacts',
+  })
+  async getNewMessageId(
+    @WorkingSessionParam session: WhatsappSession,
+  ): Promise<NewMessageIDResponse> {
+    const id = await session.generateNewMessageId();
+    return { id: id };
+  }
 }
 
 export { StatusController };

src/api/version.controller.ts

@@ -1,20 +1,26 @@
-import { Controller, Get } from '@nestjs/common';
-import {
-  ApiExtraModels,
-  ApiOperation,
-  ApiSecurity,
-  ApiTags,
-} from '@nestjs/swagger';
+import { Controller, Get, UseGuards } from '@nestjs/common';
+import { ApiOperation, ApiSecurity, ApiTags } from '@nestjs/swagger';
 
 import { WAHAEnvironment } from '../structures/environment.dto';
 import { VERSION } from '../version';
+import { PoliciesGuard } from '@waha/core/auth/policies.guard';
+import { CheckPolicies } from '@waha/core/auth/policies.decorator';
+import { CanServer } from '@waha/core/auth/policies';
+
+import { Action } from '@waha/core/auth/casl.types';
 
 @ApiSecurity('api_key')
 @Controller('api/version')
-@ApiTags('other')
+@ApiTags('🔍 Observability')
+@UseGuards(PoliciesGuard)
+@CheckPolicies(CanServer(Action.Retrieve))
 export class VersionController {
   @Get('')
-  @ApiOperation({ summary: 'Get the version of the server' })
+  @ApiOperation({
+    summary: 'Get the server version ',
+    deprecated: true,
+    description: "Use 'GET /api/server/version' instead ",
+  })
   get(): WAHAEnvironment {
     return VERSION;
   }

src/api/websocket.gateway.core.ts

@@ -0,0 +1,162 @@
+import {
+  BeforeApplicationShutdown,
+  Logger,
+  LoggerService,
+} from '@nestjs/common';
+import { sleep } from '@nestjs/terminus/dist/utils';
+import {
+  OnGatewayConnection,
+  OnGatewayDisconnect,
+  OnGatewayInit,
+  WebSocketGateway,
+  WebSocketServer,
+} from '@nestjs/websockets';
+import { SessionManager } from '@waha/core/abc/manager.abc';
+import { WebSocketAuth } from '@waha/core/auth/WebSocketAuth';
+import { WebsocketHeartbeatJob } from '@waha/nestjs/ws/WebsocketHeartbeatJob';
+import { WebSocket } from '@waha/nestjs/ws/ws';
+import { WAHAEvents, WAHAEventsWild } from '@waha/structures/enums.dto';
+import { EventWildUnmask } from '@waha/utils/events';
+import { generatePrefixedId } from '@waha/utils/ids';
+import { IncomingMessage } from 'http';
+import { URL } from 'url';
+import { Server } from 'ws';
+import { CaslAbilityFactory } from '@waha/core/auth/casl.ability';
+import { Action, session as SessionName } from '@waha/core/auth/casl.types';
+
+export enum WebSocketCloseCode {
+  NORMAL = 1000,
+  GOING_AWAY = 1001,
+  PROTOCOL_ERROR = 1002,
+  UNSUPPORTED_DATA = 1003,
+  POLICY_VIOLATION = 1008,
+  INTERNAL_ERROR = 1011,
+}
+
+@WebSocketGateway({
+  path: '/ws',
+  cors: true,
+})
+export class WebsocketGatewayCore
+  implements
+    OnGatewayInit,
+    OnGatewayConnection,
+    OnGatewayDisconnect,
+    BeforeApplicationShutdown
+{
+  HEARTBEAT_INTERVAL = 60_000;
+
+  @WebSocketServer()
+  server: Server;
+
+  private readonly logger: LoggerService;
+  private heartbeat: WebsocketHeartbeatJob;
+  private eventUnmask = new EventWildUnmask(WAHAEvents, WAHAEventsWild);
+
+  constructor(
+    private manager: SessionManager,
+    private auth: WebSocketAuth,
+    private readonly casl: CaslAbilityFactory,
+  ) {
+    this.logger = new Logger('WebsocketGateway');
+    this.heartbeat = new WebsocketHeartbeatJob(
+      this.logger,
+      this.HEARTBEAT_INTERVAL,
+    );
+  }
+
+  async handleConnection(
+    socket: WebSocket,
+    request: IncomingMessage,
+    ...args
+  ): Promise<any> {
+    // wsc - websocket client
+    socket.id = generatePrefixedId('wsc');
+
+    const user = await this.auth.validateRequest(request);
+    if (!user) {
+      // Not authorized - close connection
+      socket.close(WebSocketCloseCode.POLICY_VIOLATION, 'Unauthorized');
+      this.logger.debug(
+        `Unauthorized websocket connection attempt: ${request.url} - ${socket.id}`,
+      );
+      return;
+    }
+
+    const params = this.getParams(request);
+    let session: string = params.session;
+    const ability = this.casl.createForUser(user);
+    if (session == '*' && !ability.can(Action.Manage, 'all')) {
+      // Limit user to listen only the session events
+      session = user.session;
+    }
+
+    if (!ability.can(Action.Read, new SessionName(session))) {
+      socket.close(WebSocketCloseCode.POLICY_VIOLATION, 'Forbidden');
+      return;
+    }
+
+    this.logger.debug(`New client connected: ${request.url} - ${socket.id}`);
+    const events = params.events as WAHAEvents[];
+    this.logger.debug(
+      `Client connected to session: '${session}', events: ${events}, ${socket.id}`,
+    );
+
+    const sub = this.manager
+      .getSessionEvents(session, events)
+      .subscribe((data) => {
+        setImmediate(() => {
+          this.logger.debug(
+            `Sending data to client, event.id: ${data.id}`,
+            data,
+          );
+          socket.send(JSON.stringify(data), (err) => {
+            if (!err) {
+              return;
+            }
+            this.logger.error(`Error sending data to client: ${err}`);
+          });
+        });
+      });
+    socket.on('close', () => {
+      this.logger.debug(`Client disconnected - ${socket.id}`);
+      sub.unsubscribe();
+    });
+  }
+
+  private getParams(request: IncomingMessage) {
+    // We need only search params, so localhost is fine here
+    const query = new URL(request.url, 'http://localhost').searchParams;
+    const session = query.get('session') || '*';
+    const paramsEvents = query.getAll('events');
+    const eventsRaw = paramsEvents.length > 0 ? paramsEvents : ['*'];
+    const eventsList = eventsRaw.flatMap((value) => value.split(','));
+    const result = this.eventUnmask.unmask(eventsList);
+    if (result.unknown.length > 0) {
+      this.logger.warn(
+        `Ignoring unknown websocket events: ${result.unknown.join(', ')}`,
+      );
+    }
+    return { session, events: result.events };
+  }
+
+  handleDisconnect(socket: WebSocket): any {
+    this.logger.debug(`Client disconnected - ${socket.id}`);
+  }
+
+  async beforeApplicationShutdown(signal?: string) {
+    this.logger.log('Shutting down websocket server');
+    this.heartbeat?.stop();
+    // Allow pending messages to be sent, it can be even 1ms, just to release the event loop
+    await sleep(100);
+    this.logger.log('Websocket server is down');
+  }
+
+  afterInit(server: Server) {
+    this.logger.debug('Websocket server initialized');
+
+    this.logger.debug('Starting heartbeat service...');
+    this.heartbeat.start(server);
+    this.logger.debug('Heartbeat service started');
+  }
+}

src/apps/app_sdk/AppConsumer.ts

@@ -0,0 +1,74 @@
+import { JOB_DELAY, JOB_LOCK_TTL } from '@waha/apps/app_sdk/constants';
+import { JobLoggerWrapper } from '@waha/apps/app_sdk/JobLoggerWrapper';
+import { RMutexService } from '@waha/modules/rmutex/rmutex.service';
+import { BaseWorkerHost } from '@waha/utils/bull/BaseWorkerHost';
+import { Job } from 'bullmq';
+import { DelayedError } from 'bullmq';
+import { PinoLogger } from 'nestjs-pino';
+import { Logger } from 'pino';
+
+export interface JobDataTimeout {
+  timeout?: {
+    job?: number;
+  };
+}
+
+/**
+ * Base class for app consumers that provides common functionality
+ * like mutex locking, logging setup, and error handling.
+ */
+export abstract class AppConsumer extends BaseWorkerHost {
+  protected readonly logger: Logger;
+
+  constructor(
+    appName: string,
+    componentName: string,
+    log: PinoLogger,
+    protected readonly rmutex: RMutexService,
+  ) {
+    super();
+    this.logger = log.logger.child({
+      app: appName,
+      component: componentName,
+    });
+  }
+
+  protected signal(job) {
+    if (job.data?.timeout?.job != null) {
+      return AbortSignal.timeout(job.data?.timeout?.job);
+    }
+    // Aka never abort
+    return new AbortController().signal;
+  }
+
+  /**
+   * Executes a job with mutex locking to ensure only one job processes a specific resource at a time.
+   * @param job The job to process
+   * @param mutexKey The key to use for mutex locking
+   * @param processor The function that processes the job
+   * @returns The result of the processor function
+   */
+  protected async withMutex<T, R>(
+    job: Job<T, R, any>,
+    mutexKey: string,
+    processor: () => Promise<R>,
+  ): Promise<R> {
+    const mutex = this.rmutex.get(mutexKey, JOB_LOCK_TTL);
+    const lock = await mutex.lock();
+
+    if (!lock) {
+      const logger = new JobLoggerWrapper(job, this.logger);
+      logger.debug(
+        `Postponing job '${job.id}' for ${JOB_DELAY}ms, another job is already running the mutex.key='${mutexKey}'`,
+      );
+      await job.moveToDelayed(Date.now() + JOB_DELAY);
+      throw new DelayedError();
+    }
+
+    try {
+      return await processor();
+    } finally {
+      await lock.release();
+    }
+  }
+}

src/apps/app_sdk/AxiosLogging.ts

@@ -0,0 +1,67 @@
+import { AxiosInstance, AxiosRequestConfig, AxiosResponse } from 'axios';
+
+import { ILogger } from './ILogger';
+
+export class AxiosLogging {
+  constructor(private readonly logger: ILogger) {}
+
+  applyTo(instance: AxiosInstance) {
+    instance.interceptors.request.use(this.onRequest.bind(this));
+    instance.interceptors.response.use(
+      this.onResponse.bind(this),
+      this.onError.bind(this),
+    );
+  }
+
+  private onRequest(config: AxiosRequestConfig) {
+    const method = config.method?.toUpperCase() ?? 'GET';
+    const url = config.url ?? '';
+    const query = config.params
+      ? `?${new URLSearchParams(config.params).toString()}`
+      : '';
+    const body = config.data ? JSON.stringify(config.data) : '';
+
+    this.logger.debug(`${method} ${url}${query} ${body}`);
+    return config;
+  }
+
+  private onResponse(response: AxiosResponse) {
+    const { method, url } = response.config;
+    const status = response.status;
+    const methodStr = method?.toUpperCase() ?? 'GET';
+
+    const type: any = response.headers['content-type'];
+    // Log warnings for non-2xx/3xx responses
+    if (status < 200 || status >= 400) {
+      const data = JSON.stringify(response.data);
+      this.logger.warn(`${methodStr} ${status} ${url} ${data}`);
+      return response;
+    }
+
+    // Log debug for 2xx/3xx responses
+    this.logger.debug(`${methodStr} ${status}:OK ${url}`);
+    if (type?.startsWith('application/json')) {
+      const data = JSON.stringify(response.data);
+      this.logger.trace(`${methodStr} ${status}:OK ${url} ${data}`);
+    } else {
+      this.logger.trace(`${methodStr} ${status}:OK ${url} [${type}]`);
+    }
+
+    return response;
+  }
+
+  private onError(error: any) {
+    if (error.response) {
+      const { method, url } = error.config;
+      const status = error.response.status;
+      const message = `${
+        method?.toUpperCase() ?? 'GET'
+      } ${status} ${url} ${JSON.stringify(error.response.data)}`;
+      this.logger.error(message);
+    } else {
+      this.logger.error(`Axios error: ${error.message}`);
+    }
+
+    return Promise.reject(error);
+  }
+}

src/apps/app_sdk/BullUtils.ts

@@ -0,0 +1,26 @@
+import { BullMQAdapter } from '@bull-board/api/bullMQAdapter';
+import { BullBoardModule } from '@bull-board/nestjs';
+import { BullModule } from '@nestjs/bullmq';
+import { RegisterQueueOptions } from '@nestjs/bullmq/dist/interfaces/register-queue-options.interface';
+import { DynamicModule } from '@nestjs/common';
+
+/**
+ * Registers a queue with both BullModule and BullBoardModule
+ * This ensures that whenever a queue is registered, it's also added to the Bull Board
+ *
+ * @param options Queue options including name
+ * @returns An array of dynamic modules for both BullModule and BullBoardModule
+ */
+export function RegisterAppQueue(
+  options: RegisterQueueOptions,
+): DynamicModule[] {
+  return [
+    BullModule.registerQueue({
+      ...options,
+    }),
+    BullBoardModule.forFeature({
+      name: options.name,
+      adapter: BullMQAdapter,
+    }),
+  ];
+}

src/apps/app_sdk/ILogger.ts

@@ -0,0 +1,8 @@
+export interface ILogger {
+  fatal(log: string): void;
+  error(log: string): void;
+  warn(log: string): void;
+  info(log: string): void;
+  debug(log: string): void;
+  trace(log: string): void;
+}

src/apps/app_sdk/JobLoggerWrapper.ts

@@ -0,0 +1,58 @@
+import { Job } from 'bullmq';
+import { Logger } from 'pino';
+
+import { ILogger } from './ILogger';
+
+/**
+ * JobLoggerWrapper is a wrapper around the BullMQ Job class that provides
+ * a logger with the job ID as a child context.
+ * It allows logging messages to the job's log
+ * and also to the logger itself.
+ */
+export class JobLoggerWrapper implements ILogger {
+  private readonly logger: Logger;
+
+  constructor(
+    private job: Job,
+    logger: Logger,
+  ) {
+    this.logger = logger.child({ jobId: job.id });
+  }
+
+  fatal(log: string): void {
+    this.log(log, 'fatal');
+  }
+
+  error(log: string): void {
+    this.log(log, 'error');
+  }
+
+  warn(log: string): void {
+    this.log(log, 'warn');
+  }
+
+  info(log: string): void {
+    this.log(log, 'info');
+  }
+
+  debug(log: string): void {
+    this.log(log, 'debug');
+  }
+
+  trace(log: string): void {
+    this.log(log, 'trace');
+  }
+
+  private log(msg: string, level: string) {
+    if (!this.logger.isLevelEnabled(level)) {
+      return;
+    }
+    this.logger[level](msg);
+    const timestamp = new Date().toISOString();
+    this.job
+      .log(`[${timestamp}] ${level.toUpperCase()}: ${msg}`)
+      .catch((err) => {
+        this.logger.error(err, 'Error logging message to job');
+      });
+  }
+}

src/apps/app_sdk/JobUtils.ts

@@ -0,0 +1,108 @@
+import { Backoffs, Job } from 'bullmq';
+import { FlowJob } from 'bullmq/dist/esm/interfaces';
+
+/**
+ * Calculates the delay until the next attempt for a job.
+ *
+ * @param job The job to calculate the next attempt delay for
+ * @returns The delay in milliseconds, or null if there is no next attempt or backoff is not set
+ */
+export function NextAttemptDelayInMs(job: Job): number | null {
+  const attemptsMade = job.attemptsMade + 1;
+  const maxAttempts = job.opts?.attempts || 1;
+  // If this is the last attempt, return null
+  if (attemptsMade >= maxAttempts) {
+    return null;
+  }
+  // Normalize the backoff options
+  const backoff = Backoffs.normalize(job.opts.backoff);
+  if (!backoff) {
+    return null;
+  }
+  // Calculate the delay using Backoffs.calculate
+  const delay = Backoffs.calculate(backoff, attemptsMade, new Error(), job);
+  // The delay can be a Promise, a number, or undefined
+  if (delay === undefined) {
+    return null;
+  }
+  // If it's a Promise, we can't handle it synchronously, so return null
+  if (delay instanceof Promise) {
+    return null;
+  }
+  return delay;
+}
+
+export function NextAttemptDelayInWholeSeconds(job: Job) {
+  const delay = NextAttemptDelayInMs(job);
+  if (delay == null) {
+    return null;
+  }
+  return Math.round(delay / 1000);
+}
+
+/**
+ * Checks if a job has been retried (not on its first attempt).
+ *
+ * @param job The job to check
+ * @returns True if the job has been retried (attemptsMade > 1), false otherwise
+ */
+export function HasBeenRetried(job: Job): boolean {
+  const attemptsMade = job.attemptsMade + 1;
+  return attemptsMade > 1;
+}
+
+/**
+ * Hide chatwoot and waha from queue name for user faced messages
+ */
+export function QueueNameRepr(name: string): string {
+  // No "chatwoot" in the name always (it start with chatwoot)
+  name = name.replace('chatwoot.', '');
+  // Replace "waha" with "whatsapp"
+  name = name.replace('waha |', 'whatsapp |');
+  return name;
+}
+
+let base =
+  process.env.WAHA_PUBLIC_URL ||
+  process.env.WAHA_BASE_URL ||
+  'http://localhost:3000';
+// cut / at the end
+base = base.replace(/\/+$/, '');
+
+export function JobLink(job: Job): { text: string; url: string } {
+  // Use repr name for text
+  const name = QueueNameRepr(job.queueName);
+  const text = `${name} => ${job.id}`;
+  // Use original queue name in the URL
+  const queue = encodeURIComponent(job.queueName);
+  const id = encodeURIComponent(job.id);
+  const url = `${base}/jobs/queue/${queue}/${id}`;
+  return { text: text, url: url };
+}
+
+/**
+ * Chain jobs so that they run one at a time
+ * A | B | C
+ * to
+ * A -> B -> C
+ */
+export function ChainJobsOneAtATime(jobs: FlowJob[]): FlowJob {
+  if (jobs.length == 0) {
+    throw new Error('No jobs provided');
+  }
+
+  for (const job of jobs) {
+    if (job.children.length != 0) {
+      throw new Error('Jobs with children are not supported');
+    }
+  }
+  const left = [...jobs];
+  const root = left.pop();
+  let parent = root;
+  while (left.length != 0) {
+    const job = left.pop();
+    parent.children = [job];
+    parent = job;
+  }
+  return root;
+}

src/apps/app_sdk/api/apps.controller.ts

@@ -0,0 +1,185 @@
+import {
+  Body,
+  Controller,
+  Delete,
+  ForbiddenException,
+  Get,
+  Inject,
+  NotFoundException,
+  Param,
+  Post,
+  Put,
+  Query,
+  Req,
+  UseGuards,
+  UsePipes,
+} from '@nestjs/common';
+import { ApiOperation, ApiParam, ApiSecurity, ApiTags } from '@nestjs/swagger';
+import { AppName } from '@waha/apps/app_sdk/apps/apps';
+import { UniqueAppResolver } from '@waha/apps/app_sdk/services/UniqueAppResolver';
+import {
+  AppsService,
+  IAppsService,
+} from '@waha/apps/app_sdk/services/IAppsService';
+import { SessionManager } from '@waha/core/abc/manager.abc';
+import { CheckPolicies } from '@waha/core/auth/policies.decorator';
+import { PoliciesGuard } from '@waha/core/auth/policies.guard';
+import {
+  CanServer,
+  CanSession,
+  FromBody,
+  FromParam,
+  FromQuery,
+} from '@waha/core/auth/policies';
+import { Action, session as SessionName } from '@waha/core/auth/casl.types';
+import { WAHAValidationPipe } from '@waha/nestjs/pipes/WAHAValidationPipe';
+
+import { GetApp } from '../apps/registry';
+import { App } from '../dto/app.dto';
+import { ListAppsQuery } from '../dto/query.dto';
+
+@ApiSecurity('api_key')
+@Controller('api/apps')
+@ApiTags('🧩 Apps')
+@UseGuards(PoliciesGuard)
+export class AppsController {
+  constructor(
+    @Inject(AppsService)
+    private appsService: IAppsService,
+    private manager: SessionManager,
+    private resolver: UniqueAppResolver,
+  ) {}
+
+  @Get('/')
+  @ApiOperation({ summary: 'List all apps for a session' })
+  @CheckPolicies(CanSession(Action.App, FromQuery('session')))
+  @UsePipes(new WAHAValidationPipe())
+  async list(
+    @Query(new WAHAValidationPipe()) query: ListAppsQuery,
+  ): Promise<App[]> {
+    return this.appsService.list(this.manager, query.session);
+  }
+
+  @Post('/')
+  @ApiOperation({ summary: 'Create a new app' })
+  @CheckPolicies(CanSession(Action.App, FromBody('session')))
+  @UsePipes(new WAHAValidationPipe())
+  async create(@Body() app: App): Promise<App> {
+    const result = await this.appsService.create(this.manager, app);
+    const isRunning = this.manager.isRunning(app.session);
+    if (
+      isRunning &&
+      app.enabled &&
+      GetApp(app.app)?.definition.restartOnChange
+    ) {
+      await this.manager.restart(app.session);
+    }
+    return result;
+  }
+
+  @Get('/:id')
+  @ApiOperation({ summary: 'Get app by ID' })
+  @CheckPolicies(CanServer(Action.Retrieve))
+  @UsePipes(new WAHAValidationPipe())
+  async get(@Param('id') id: string, @Req() req: any): Promise<App> {
+    const app = await this.appsService.get(this.manager, id);
+    if (!app) {
+      throw new NotFoundException(`App '${id}' not found`);
+    }
+    if (!req.ability?.can(Action.App, new SessionName(app.session))) {
+      throw new ForbiddenException();
+    }
+    return app;
+  }
+
+  @Put('/:id')
+  @ApiOperation({ summary: 'Update an existing app' })
+  @CheckPolicies(CanServer(Action.Retrieve))
+  @UsePipes(new WAHAValidationPipe())
+  async update(
+    @Param('id') id: string,
+    @Body() app: App,
+    @Req() req: any,
+  ): Promise<App> {
+    const existing = await this.appsService.get(this.manager, id);
+    if (existing) {
+      if (!req.ability?.can(Action.App, new SessionName(existing.session))) {
+        throw new ForbiddenException();
+      }
+    } else {
+      if (!req.ability?.can(Action.App, new SessionName(app.session))) {
+        throw new ForbiddenException();
+      }
+    }
+
+    if (!app.id) {
+      app.id = id;
+    } else if (app.id !== id) {
+      throw new NotFoundException(
+        `App ID in path (${id}) does not match ID in body (${app.id})`,
+      );
+    }
+
+    const result = await this.appsService.upsert(this.manager, app);
+    const isRunning = this.manager.isRunning(result.session);
+    if (isRunning && GetApp(result.app)?.definition.restartOnChange) {
+      await this.manager.restart(result.session);
+    }
+    return result;
+  }
+
+  @Delete('/:id')
+  @ApiOperation({ summary: 'Delete an app' })
+  @CheckPolicies(CanServer(Action.Retrieve))
+  @UsePipes(new WAHAValidationPipe())
+  async delete(@Param('id') id: string, @Req() req: any): Promise<void> {
+    const existing = await this.appsService.get(this.manager, id);
+    if (!existing) {
+      throw new NotFoundException(`App '${id}' not found`);
+    }
+    if (!req.ability?.can(Action.App, new SessionName(existing.session))) {
+      throw new ForbiddenException();
+    }
+    const app = await this.appsService.delete(this.manager, id);
+    const isRunning = this.manager.isRunning(app.session);
+    if (isRunning && GetApp(app.app)?.definition.restartOnChange) {
+      await this.manager.restart(app.session);
+    }
+  }
+
+  @Post('/:id/purge')
+  @ApiOperation({
+    summary: 'Purge app storage by app ID',
+    description:
+      "Delete the app's stored data (database rows, caches) while keeping the app configured.",
+  })
+  @CheckPolicies(CanServer(Action.Retrieve))
+  @UsePipes(new WAHAValidationPipe())
+  async purge(@Param('id') id: string, @Req() req: any): Promise<App> {
+    const existing = await this.appsService.get(this.manager, id);
+    if (!existing) {
+      throw new NotFoundException(`App '${id}' not found`);
+    }
+    if (!req.ability?.can(Action.App, new SessionName(existing.session))) {
+      throw new ForbiddenException();
+    }
+    return await this.appsService.purge(this.manager, id);
+  }
+
+  @Post('/:app/:session/purge')
+  @ApiOperation({
+    summary: 'Purge app storage by app name and session',
+    description:
+      "Delete the unique app's stored data for the session. The app must be enabled.",
+  })
+  @ApiParam({ name: 'app', enum: AppName })
+  @CheckPolicies(CanSession(Action.App, FromParam('session')))
+  @UsePipes(new WAHAValidationPipe())
+  async purgeUniqueApp(
+    @Param('app') appName: string,
+    @Param('session') session: string,
+  ): Promise<App> {
+    const app = await this.resolver.getEnabledApp(session, appName);
+    return await this.appsService.purge(this.manager, app.id);
+  }
+}

src/apps/app_sdk/api/tags.ts

@@ -0,0 +1,28 @@
+import { AppApiTag } from '@waha/apps/app_sdk/apps/openapi';
+import { AppRuntimeConfig } from '@waha/apps/app_sdk/apps/AppRuntime';
+import { GetApps } from '@waha/apps/app_sdk/apps/registry';
+
+export interface ApiTag {
+  name: string;
+  description: string;
+}
+
+/**
+ * OpenAPI tags for all registered apps - one "🧩 Apps: {Title}" tag per app,
+ * so app-specific endpoints get their own section in Swagger.
+ * Includes disabled apps too (only their openapi metadata is used) - some app
+ * controllers are served even when apps are disabled ('disabledControllers');
+ * their description is prefixed with "DISABLED" to make the state visible.
+ */
+export function GetAppsApiTags(): ApiTag[] {
+  return GetApps().map((app) => {
+    const enabled = AppRuntimeConfig.HasApp(app.name);
+    const description = enabled
+      ? app.openapi.description
+      : `DISABLED - ${app.openapi.description}`;
+    return {
+      name: AppApiTag(app.openapi),
+      description: description,
+    };
+  });
+}

src/apps/app_sdk/apps/AppRuntime.ts

@@ -0,0 +1,57 @@
+import { AppEnv } from '@waha/apps/app_sdk/env';
+import { AppModule } from '@waha/apps/app_sdk/apps/definition';
+import { GetApps } from '@waha/apps/app_sdk/apps/registry';
+
+class AppRuntimeConfigC {
+  private constructor(private apps: AppModule[] | null) {}
+
+  static FromEnv(env: typeof AppEnv) {
+    if (!env.enabled) {
+      return new AppRuntimeConfigC(null);
+    }
+    let apps: AppModule[] = GetApps();
+    // Include
+    if (env.on && env.on.length > 0) {
+      apps = apps.filter((app) => env.on!.includes(app.name));
+    }
+    // Exclude
+    if (env.off && env.off.length > 0) {
+      apps = apps.filter((app) => !env.off!.includes(app.name));
+    }
+    return new AppRuntimeConfigC(apps);
+  }
+
+  Enabled() {
+    return this.apps !== null;
+  }
+
+  GetApps() {
+    return this.apps || [];
+  }
+
+  GetAppsWithMigration() {
+    return this.GetApps().filter((app) => app.definition.migrations);
+  }
+
+  GetAppsRequiringPlainKey() {
+    return this.GetApps().filter((app) => app.definition.plainkey);
+  }
+
+  GetAppsRequiringQueue() {
+    return this.GetApps().filter((app) => app.definition.queue);
+  }
+
+  HasApp(name: string) {
+    return this.GetApps().some((app) => app.name === name);
+  }
+
+  HasAppsRequiringPlainKey() {
+    return this.GetAppsRequiringPlainKey().length > 0;
+  }
+
+  HasAppsRequiringQueue() {
+    return this.GetAppsRequiringQueue().length > 0;
+  }
+}
+
+export const AppRuntimeConfig = AppRuntimeConfigC.FromEnv(AppEnv);

src/apps/app_sdk/apps/apps.ts

@@ -0,0 +1,37 @@
+import { ArgentinePhoneNumbersAppConfig } from '@waha/apps/argentine-phone-numbers/dto';
+import { Type } from '@nestjs/common';
+import { BrazilianPhoneNumbersAppConfig } from '@waha/apps/brazilian-phone-numbers/dto';
+import { CallsAppConfig } from '@waha/apps/calls/dto/config.dto';
+import { ChatWootAppConfig } from '@waha/apps/chatwoot/dto/config.dto';
+import { McpAppConfig } from '@waha/apps/mcp/dto/config.dto';
+import { MexicanPhoneNumbersAppConfig } from '@waha/apps/mexican-phone-numbers/dto';
+import { PhoneNumbersAppConfig } from '@waha/apps/phone-numbers/dto/config.dto';
+
+export enum AppName {
+  argentinePhoneNumbers = 'argentine-phone-numbers',
+  brazilianPhoneNumbers = 'brazilian-phone-numbers',
+  chatwoot = 'chatwoot',
+  calls = 'calls',
+  mcp = 'mcp',
+  mexicanPhoneNumbers = 'mexican-phone-numbers',
+  phoneNumbers = 'phone-numbers',
+}
+
+/**
+ * DTO classes used to transform and validate App.config, by app name.
+ * Kept separate from the registry so DTOs (imported by core structures) can resolve config classes
+ * without pulling in every app module (controllers, services, queues) - that creates require cycles.
+ */
+export const AppConfigClasses: Record<AppName, Type<any>> = {
+  [AppName.argentinePhoneNumbers]: ArgentinePhoneNumbersAppConfig,
+  [AppName.brazilianPhoneNumbers]: BrazilianPhoneNumbersAppConfig,
+  [AppName.phoneNumbers]: PhoneNumbersAppConfig,
+  [AppName.calls]: CallsAppConfig,
+  [AppName.chatwoot]: ChatWootAppConfig,
+  [AppName.mcp]: McpAppConfig,
+  [AppName.mexicanPhoneNumbers]: MexicanPhoneNumbersAppConfig,
+};
+
+export function GetAppConfigClass(name: AppName): Type<any> {
+  return AppConfigClasses[name] ?? Object;
+}

src/apps/app_sdk/apps/definition.ts

@@ -0,0 +1,63 @@
+import { Type } from '@nestjs/common';
+import { AppName } from '@waha/apps/app_sdk/apps/apps';
+import { AppOpenAPI } from '@waha/apps/app_sdk/apps/openapi';
+import { GetApp } from '@waha/apps/app_sdk/apps/registry';
+import { IAppService } from '@waha/apps/app_sdk/services/IAppService';
+
+export interface AppDefinition {
+  // If app requires WAHA_API_KEY_PLAIN to work
+  plainkey: boolean;
+  // If app requires queue to work
+  queue: boolean;
+  // If app has any migrations
+  migrations: boolean;
+  // If adding, updating, or removing this app requires a session restart
+  restartOnChange: boolean;
+  // If only one instance of this app is allowed per session
+  unique: boolean;
+}
+
+// NestJS module parts, included when the app is enabled in runtime configuration
+export interface AppNestJS {
+  imports: any[];
+  controllers: any[];
+  providers: any[];
+}
+
+/**
+ * Contract for the default export of 'src/apps/<name>/app.module.ts'.
+ * Each app self-describes with this and gets listed in the registry ('apps/registry.ts').
+ */
+export interface AppModule {
+  // App name
+  name: AppName;
+  // OpenAPI metadata (tag title, description) from 'src/apps/<name>/openapi.ts'
+  openapi: AppOpenAPI;
+  // Static app metadata (requirements, behavior flags)
+  definition: AppDefinition;
+  // NestJS module parts
+  nestjs: AppNestJS;
+  // Service implementing app lifecycle hooks; must also be listed in 'nestjs.providers'
+  Service: Type<IAppService>;
+}
+
+export function isUniqueApp(name: AppName): boolean {
+  return GetApp(name)?.definition.unique === true;
+}
+
+// Returns the first unique AppName that appears more than once in the list, or null
+export function findDuplicateUniqueApp(
+  apps: Array<{ app: AppName }>,
+): AppName | null {
+  const seen = new Set<AppName>();
+  for (const app of apps) {
+    if (!isUniqueApp(app.app)) {
+      continue;
+    }
+    if (seen.has(app.app)) {
+      return app.app;
+    }
+    seen.add(app.app);
+  }
+  return null;
+}

src/apps/app_sdk/apps/openapi.ts

@@ -0,0 +1,14 @@
+/**
+ * OpenAPI metadata for an app, defined inline in the app's AppModule ('openapi' field).
+ * The registry applies the "🧩 Apps: {Title}" tag to every controller in 'nestjs.controllers',
+ * so app controllers do not declare @ApiTags themselves - a new app only touches its own folder.
+ */
+export interface AppOpenAPI {
+  title: string;
+  description: string;
+}
+
+// OpenAPI tag for app-specific endpoints - "🧩 Apps: {Title}"
+export function AppApiTag(openapi: AppOpenAPI): string {
+  return `🧩 Apps: ${openapi.title}`;
+}

src/apps/app_sdk/apps/registry.ts

@@ -0,0 +1,40 @@
+import ArgentinePhoneNumbersAppModule from '@waha/apps/argentine-phone-numbers/app.module';
+import { ApiTags } from '@nestjs/swagger';
+import BrazilianPhoneNumbersAppModule from '@waha/apps/brazilian-phone-numbers/app.module';
+import { AppModule } from '@waha/apps/app_sdk/apps/definition';
+import { AppApiTag } from '@waha/apps/app_sdk/apps/openapi';
+import CallsAppModule from '@waha/apps/calls/app.module';
+import ChatWootAppModule from '@waha/apps/chatwoot/app.module';
+import McpAppModule from '@waha/apps/mcp/app.module';
+import MexicanPhoneNumbersAppModule from '@waha/apps/mexican-phone-numbers/app.module';
+import PhoneNumbersAppModule from '@waha/apps/phone-numbers/app.module';
+
+/**
+ * Registry of available apps.
+ * Add new apps here - the rest of app_sdk works off this list.
+ */
+const APPS: AppModule[] = [
+  ArgentinePhoneNumbersAppModule,
+  BrazilianPhoneNumbersAppModule,
+  CallsAppModule,
+  ChatWootAppModule,
+  McpAppModule,
+  MexicanPhoneNumbersAppModule,
+  PhoneNumbersAppModule,
+];
+
+// Tag every app controller with the app's OpenAPI tag ("🧩 Apps: {Title}") from AppModule.openapi,
+// so controllers do not declare @ApiTags themselves (they cannot import their own app.module - require cycle).
+for (const app of APPS) {
+  for (const controller of app.nestjs.controllers) {
+    ApiTags(AppApiTag(app.openapi))(controller);
+  }
+}
+
+export function GetApps(): AppModule[] {
+  return APPS;
+}
+
+export function GetApp(name: string): AppModule | undefined {
+  return APPS.find((app) => app.name === name);
+}

src/apps/app_sdk/auth.ts

@@ -0,0 +1,25 @@
+import * as process from 'node:process';
+
+import { parseBool } from '@waha/helpers';
+import * as basicAuth from 'express-basic-auth';
+import { Auth } from '@waha/core/auth/config';
+
+export function BullAuthMiddleware() {
+  let username = Auth.dashboard.username.value || '';
+  let password = Auth.dashboard.password.value || '';
+  if (process.env.WAHA_DASHBOARD_ENABLED) {
+    const enabled = parseBool(process.env.WAHA_DASHBOARD_ENABLED);
+    if (!enabled) {
+      // Generate a random uuid4 username/password to effectively disable access
+      username = 'admin';
+      password = crypto.randomUUID();
+    }
+  }
+
+  return basicAuth({
+    challenge: true,
+    users: {
+      [String(username)]: String(password),
+    },
+  });
+}

src/apps/app_sdk/constants.ts

@@ -0,0 +1,47 @@
+import { DefaultJobOptions } from 'bullmq';
+
+export const JOB_DELAY = 1_000;
+export const JOB_LOCK_TTL = 20_000;
+export const JOB_CONCURRENCY =
+  parseInt(process.env.WAHA_APPS_JOBS_CONCURRENCY) || 50;
+
+function jobRemoveOptions() {
+  // in seconds
+  const HOUR = 60 * 60;
+  const DAY = 24 * HOUR;
+  return {
+    removeOnComplete: {
+      age:
+        parseInt(process.env.WAHA_APPS_JOBS_REMOVE_ON_COMPLETE_AGE) || 3 * DAY,
+      count:
+        parseInt(process.env.WAHA_APPS_JOBS_REMOVE_ON_COMPLETE_COUNT) || 1000,
+    },
+    removeOnFail: {
+      age: parseInt(process.env.WAHA_APPS_JOBS_REMOVE_ON_FAIL_AGE) || 31 * DAY,
+      count: parseInt(process.env.WAHA_APPS_JOBS_REMOVE_ON_FAIL_COUNT) || 1000,
+    },
+  };
+}
+
+export const JobRemoveOptions = jobRemoveOptions();
+
+function exponentialRetriesJobOptions(): DefaultJobOptions {
+  return {
+    attempts: parseInt(process.env.WAHA_APPS_JOBS_ATTEMPTS) || 3,
+    delay: parseInt(process.env.WAHA_APPS_JOBS_DELAY) || 0,
+    backoff: {
+      type: process.env.WAHA_APPS_JOBS_BACKOFF_TYPE || 'exponential',
+      delay: parseInt(process.env.WAHA_APPS_JOBS_BACKOFF_DELAY) || 1000,
+    },
+  };
+}
+
+export const ExponentialRetriesJobOptions = exponentialRetriesJobOptions();
+
+export const NoRetriesJobOptions: DefaultJobOptions = {
+  attempts: 1,
+};
+
+export function merge(...args: any[]) {
+  return Object.assign({}, ...args);
+}

src/apps/app_sdk/dto/app.dto.ts

@@ -0,0 +1,49 @@
+import { Type } from 'class-transformer';
+import {
+  IsBoolean,
+  IsEnum,
+  IsOptional,
+  IsString,
+  ValidateNested,
+} from 'class-validator';
+import { ApiExtraModels, ApiProperty } from '@nestjs/swagger';
+import {
+  AppConfigClasses,
+  AppName,
+  GetAppConfigClass,
+} from '@waha/apps/app_sdk/apps/apps';
+
+export class App<T = any> {
+  @IsString()
+  id: string;
+
+  @IsString()
+  session: string;
+
+  // App name (aka type)
+  @IsEnum(AppName)
+  app: AppName;
+
+  @ApiProperty({
+    description:
+      'Enable or disable this app without deleting it. If omitted, treated as enabled (true).',
+    required: false,
+    default: true,
+  })
+  @IsOptional()
+  @IsBoolean()
+  enabled?: boolean = true;
+
+  @ValidateNested()
+  @Type((options) => {
+    const name = options?.object?.app;
+    if (!name) {
+      return Object;
+    }
+    return GetAppConfigClass(name);
+  })
+  config: T;
+}
+
+// Swagger models for app configs
+ApiExtraModels(...Object.values(AppConfigClasses))(App);

src/apps/app_sdk/dto/query.dto.ts

@@ -0,0 +1,13 @@
+import { ApiProperty } from '@nestjs/swagger';
+import { IsNotEmpty, IsString } from 'class-validator';
+
+export class ListAppsQuery {
+  @ApiProperty({
+    example: 'default',
+    required: true,
+    description: 'Session name to list apps for',
+  })
+  @IsString()
+  @IsNotEmpty()
+  session: string;
+}

src/apps/app_sdk/env.ts

@@ -0,0 +1,42 @@
+import { parseBool } from '@waha/helpers';
+import { GetApps } from '@waha/apps/app_sdk/apps/registry';
+
+// Apps that don't require queue (Redis) - derived from AppDefinition
+const IN_MEMORY_APPS = GetApps()
+  .filter((app) => !app.definition.queue)
+  .map((app) => app.name);
+
+function parseCommaSeparatedList(value: string | undefined): string[] {
+  if (!value) {
+    return null;
+  }
+  return value.split(',').map((item) => item.trim());
+}
+
+function isMongoDB(): boolean {
+  return !!process.env.WHATSAPP_SESSIONS_MONGO_URL;
+}
+
+function buildAppEnv() {
+  const enabled = process.env.WAHA_APPS_ENABLED;
+  const on = process.env.WAHA_APPS_ON;
+  const off = process.env.WAHA_APPS_OFF;
+
+  // Default if not mongodb
+  const isUserConfigured = enabled !== undefined || on !== undefined;
+  if (!isUserConfigured && !isMongoDB()) {
+    return {
+      enabled: true,
+      on: IN_MEMORY_APPS,
+      off: parseCommaSeparatedList(off),
+    };
+  }
+
+  return {
+    enabled: parseBool(enabled),
+    on: parseCommaSeparatedList(on),
+    off: parseCommaSeparatedList(off),
+  };
+}
+
+export const AppEnv = buildAppEnv();

src/apps/app_sdk/jest/JestLogger.ts

@@ -0,0 +1,12 @@
+import { ILogger } from '@waha/apps/app_sdk/ILogger';
+
+export function JestLogger(): ILogger {
+  return {
+    fatal: jest.fn(),
+    error: jest.fn(),
+    warn: jest.fn(),
+    info: jest.fn(),
+    debug: jest.fn(),
+    trace: jest.fn(),
+  };
+}

src/apps/app_sdk/migrations.ts

@@ -0,0 +1,32 @@
+import * as path from 'node:path';
+
+import { Knex } from 'knex';
+import { AppRuntimeConfig } from '@waha/apps/app_sdk/apps/AppRuntime';
+
+function migrateSDK(knex: Knex): Promise<any> {
+  const config = {
+    directory: `${__dirname}/migrations`,
+    tableName: 'apps_migrations',
+    loadExtensions: ['.js'],
+  };
+  return knex.migrate.latest(config);
+}
+
+function migrateApp(knex: Knex, app: string): Promise<any> {
+  // one level upp
+  const appsDirectory = path.join(__dirname, '..', '..', 'apps');
+  const directory = path.join(appsDirectory, app, 'migrations');
+  const config = {
+    directory: directory,
+    tableName: `app_${app}_migrations`,
+    loadExtensions: ['.js'],
+  };
+  return knex.migrate.latest(config);
+}
+
+export async function migrate(knex: Knex) {
+  await migrateSDK(knex);
+  for (const app of AppRuntimeConfig.GetAppsWithMigration()) {
+    await migrateApp(knex, app.name);
+  }
+}

src/apps/app_sdk/migrations/001_init_apps.ts

@@ -0,0 +1,22 @@
+import { Knex } from 'knex';
+
+exports.up = function (knex: Knex) {
+  return knex.schema
+    .createTable('apps', function (table) {
+      table.increments('pk');
+      table.string('id', 64);
+      table.string('session', 64);
+      table.string('app', 64);
+      table.json('config');
+    })
+    .table('apps', function (table) {
+      table.unique(['pk']);
+      table.index(['session']);
+      table.index(['id']);
+      table.unique(['id']);
+    });
+};
+
+exports.down = function (knex: Knex) {
+  return knex.schema.dropTable('apps');
+};

src/apps/app_sdk/migrations/002_add_enabled_to_apps.ts

@@ -0,0 +1,26 @@
+import { Knex } from 'knex';
+
+exports.up = async function (knex: Knex) {
+  // Add a boolean column 'enabled' defaulting to true and not nullable.
+  const hasColumn = await knex.schema.hasColumn('apps', 'enabled');
+  if (!hasColumn) {
+    await knex.schema.alterTable('apps', (table) => {
+      table.boolean('enabled').defaultTo(true);
+    });
+    // Ensure existing rows have enabled=true
+    await knex('apps').update({ enabled: true });
+    // Make the column NOT NULL
+    await knex.schema.alterTable('apps', (table) => {
+      table.boolean('enabled').notNullable().defaultTo(true).alter();
+    });
+  }
+};
+
+exports.down = async function (knex: Knex) {
+  const hasColumn = await knex.schema.hasColumn('apps', 'enabled');
+  if (hasColumn) {
+    await knex.schema.alterTable('apps', (table) => {
+      table.dropColumn('enabled');
+    });
+  }
+};

src/apps/app_sdk/services/AppsDisabledService.ts

@@ -0,0 +1,75 @@
+import { Injectable, UnprocessableEntityException } from '@nestjs/common';
+import { IAppsService } from '@waha/apps/app_sdk/services/IAppsService';
+import { DataStore } from '@waha/core/abc/DataStore';
+import { SessionManager } from '@waha/core/abc/manager.abc';
+import { WhatsappSession } from '@waha/core/abc/session.abc';
+import { Knex } from 'knex';
+
+import { App } from '../dto/app.dto';
+
+class AppsIsDisabledError extends UnprocessableEntityException {
+  constructor() {
+    super(
+      "Apps are disabled. Enable it by setting 'WAHA_APPS_ENABLED=True' environment variable.",
+    );
+  }
+}
+
+@Injectable()
+export class AppsDisabledService implements IAppsService {
+  async list(manager: SessionManager, session: string): Promise<App[]> {
+    throw new AppsIsDisabledError();
+  }
+
+  async get(manager: SessionManager, appId: string): Promise<App | null> {
+    throw new AppsIsDisabledError();
+  }
+
+  async create(manager: SessionManager, app: App): Promise<App> {
+    throw new AppsIsDisabledError();
+  }
+
+  async upsert(manager: SessionManager, app: App): Promise<App> {
+    throw new AppsIsDisabledError();
+  }
+
+  async update(manager: SessionManager, app: App): Promise<App> {
+    throw new AppsIsDisabledError();
+  }
+
+  async delete(manager: SessionManager, appId: string): Promise<App> {
+    throw new AppsIsDisabledError();
+  }
+
+  async purge(manager: SessionManager, appId: string): Promise<App> {
+    throw new AppsIsDisabledError();
+  }
+
+  async purgeBySession(manager: SessionManager, session: string) {
+    return;
+  }
+
+  async removeBySession(manager: SessionManager, session: string) {
+    return;
+  }
+
+  migrate(knex: Knex<any, any[]>): Promise<void> {
+    return;
+  }
+
+  async beforeSessionStart(session: WhatsappSession, store: DataStore) {
+    return;
+  }
+
+  async afterSessionStart(session: WhatsappSession, store: DataStore) {
+    return;
+  }
+
+  async syncSessionApps(
+    manager: SessionManager,
+    sessionName: string,
+    apps?: App[] | null,
+  ): Promise<void> {
+    throw new AppsIsDisabledError();
+  }
+}

src/apps/app_sdk/services/AppsEnabledService.ts

@@ -0,0 +1,326 @@
+import {
+  Injectable,
+  NotFoundException,
+  UnprocessableEntityException,
+} from '@nestjs/common';
+import { ModuleRef } from '@nestjs/core';
+import { migrate } from '@waha/apps/app_sdk/migrations';
+import { IAppService } from '@waha/apps/app_sdk/services/IAppService';
+import { IAppsService } from '@waha/apps/app_sdk/services/IAppsService';
+import { DataStore } from '@waha/core/abc/DataStore';
+import { SessionManager } from '@waha/core/abc/manager.abc';
+import { WhatsappSession } from '@waha/core/abc/session.abc';
+import { generatePrefixedId } from '@waha/utils/ids';
+import { Knex } from 'knex';
+import { InjectPinoLogger, PinoLogger } from 'nestjs-pino';
+
+import { App } from '../dto/app.dto';
+import { AppRepository } from '../storage/AppRepository';
+import { AppRuntimeConfig } from '@waha/apps/app_sdk/apps/AppRuntime';
+import {
+  findDuplicateUniqueApp,
+  isUniqueApp,
+} from '@waha/apps/app_sdk/apps/definition';
+import { GetApp } from '@waha/apps/app_sdk/apps/registry';
+
+export class AppDisableError extends UnprocessableEntityException {
+  constructor(app: string) {
+    super(
+      `App '${app}' is disabled in runtime configuration - adjust WAHA_APPS_ON / WAHA_APPS_OFF environment variables to enable it.`,
+    );
+  }
+}
+
+export class AppUniquePerSessionError extends UnprocessableEntityException {
+  constructor(app: string, session: string, existingAppId: string) {
+    super(
+      `Only one '${app}' app is allowed per session. ` +
+        `Session '${session}' already has a '${app}' app with ID '${existingAppId}'.`,
+    );
+  }
+}
+
+@Injectable()
+export class AppsEnabledService implements IAppsService {
+  constructor(
+    @InjectPinoLogger('AppsService')
+    protected logger: PinoLogger,
+    private readonly moduleRef: ModuleRef,
+  ) {}
+
+  async list(manager: SessionManager, session: string): Promise<App[]> {
+    const knex = manager.store.getWAHADatabase();
+    const repo = new AppRepository(knex);
+    const apps = await repo.getAllBySession(session);
+    for (const app of apps) {
+      delete app.pk;
+      const service = this.getAppService(app);
+      await service?.enrich(manager, app);
+    }
+    return apps;
+  }
+
+  async create(manager: SessionManager, app: App): Promise<App> {
+    await this.checkSessionExists(manager, app.session);
+    app.id = app.id || generatePrefixedId('app');
+
+    const knex = manager.store.getWAHADatabase();
+    const repo = new AppRepository(knex);
+
+    const existingApp = await repo.getById(app.id);
+    if (existingApp) {
+      throw new Error(`App with ID '${app.id}' already exists.`);
+    }
+
+    // Validate only one instance of a unique app per session
+    if (isUniqueApp(app.app)) {
+      const existingApps = await repo.getAllBySession(app.session);
+      const duplicateApp = existingApps.find(
+        (existingApp) => existingApp.app === app.app,
+      );
+      if (duplicateApp) {
+        throw new AppUniquePerSessionError(
+          app.app,
+          app.session,
+          duplicateApp.id,
+        );
+      }
+    }
+
+    const service = this.getAppService(app);
+    if (app.enabled && !service && !AppRuntimeConfig.HasApp(app.app)) {
+      throw new AppDisableError(app.app);
+    }
+    service?.validate(app);
+    // Only run beforeCreated when app is enabled (default true if omitted)
+    if (app.enabled !== false) {
+      await service.beforeCreated(app);
+    }
+
+    const result = await repo.save(app);
+    delete result.pk;
+    if (app.enabled !== false) {
+      await service?.afterCreated(manager, result);
+    }
+    return result;
+  }
+
+  async get(manager: SessionManager, appId: string): Promise<App | null> {
+    const knex = manager.store.getWAHADatabase();
+    const repo = new AppRepository(knex);
+    const app = await repo.getById(appId);
+    if (!app) {
+      return null;
+    }
+    delete (app as any).pk;
+    const service = this.getAppService(app);
+    await service?.enrich(manager, app);
+    return app;
+  }
+
+  async upsert(manager: SessionManager, app: App) {
+    return await this.update(manager, app, true);
+  }
+
+  async update(
+    manager: SessionManager,
+    app: App,
+    upsert: boolean = false,
+  ): Promise<App> {
+    await this.checkSessionExists(manager, app.session);
+    const knex = manager.store.getWAHADatabase();
+    const repo = new AppRepository(knex);
+    const savedApp = await repo.getById(app.id);
+    if (!savedApp && upsert) {
+      return this.create(manager, app);
+    }
+
+    if (!savedApp) {
+      throw new NotFoundException(`App '${app.id}' not found`);
+    }
+    if (savedApp.app != app.app) {
+      throw new Error(
+        `Can not change app type. Delete and create a new app. Before type: '${savedApp.app}' After type: '${app.app}'`,
+      );
+    }
+    if (savedApp.session != app.session) {
+      throw new Error(
+        `Can not change session. Delete and create a new app. Before session: '${savedApp.session}' After session: '${app.session}'`,
+      );
+    }
+
+    const service = this.getAppService(app);
+    if (app.enabled && !service && !AppRuntimeConfig.HasApp(app.app)) {
+      throw new AppDisableError(app.app);
+    }
+    service?.validate(app);
+
+    const hasEnabledChange = savedApp.enabled !== app.enabled;
+
+    if (hasEnabledChange) {
+      if (app.enabled) {
+        await service?.beforeEnabled(manager, savedApp, app);
+      } else {
+        await service?.beforeDisabled(manager, savedApp, app);
+      }
+    } else {
+      await service?.beforeUpdated(manager, savedApp, app);
+    }
+    await repo.update(app.id, app);
+    const updated = await repo.getById(app.id);
+    delete (updated as any)?.pk;
+    return updated!;
+  }
+
+  async delete(manager: SessionManager, appId: string): Promise<App> {
+    const knex = manager.store.getWAHADatabase();
+    const repo = new AppRepository(knex);
+    const app = await repo.getById(appId);
+    if (!app) {
+      throw new NotFoundException(`App '${appId}' not found`);
+    }
+    const service = this.getAppService(app);
+    await service?.beforeDeleted(manager, app);
+    await repo.delete(app.id);
+    delete app.pk;
+    return app;
+  }
+
+  async purge(manager: SessionManager, appId: string): Promise<App> {
+    const knex = manager.store.getWAHADatabase();
+    const repo = new AppRepository(knex);
+    const app = await repo.getById(appId);
+    if (!app) {
+      throw new NotFoundException(`App '${appId}' not found`);
+    }
+    const service = this.getAppService(app);
+    if (!service) {
+      throw new AppDisableError(app.app);
+    }
+    await service.purge(manager, app);
+    delete app.pk;
+    return app;
+  }
+
+  async purgeBySession(manager: SessionManager, session: string) {
+    const knex = manager.store.getWAHADatabase();
+    const repo = new AppRepository(knex);
+    const apps = await repo.getAllBySession(session);
+    for (const app of apps) {
+      const service = this.getAppService(app);
+      if (!service) {
+        continue;
+      }
+      await service.purge(manager, app);
+    }
+  }
+
+  async removeBySession(manager: SessionManager, session: string) {
+    const knex = manager.store.getWAHADatabase();
+    const repo = new AppRepository(knex);
+    const apps = await repo.getAllBySession(session);
+    for (const app of apps) {
+      const service = this.getAppService(app);
+      await service?.beforeSessionDeleted(manager, app);
+    }
+    await repo.deleteBySession(session);
+  }
+
+  async beforeSessionStart(session: WhatsappSession, store: DataStore) {
+    const knex = store.getWAHADatabase();
+    const repo = new AppRepository(knex);
+    const apps = await repo.getEnabledBySession(session.name);
+    for (const app of apps) {
+      const service = this.getAppService(app);
+      if (!service && !AppRuntimeConfig.HasApp(app.app)) {
+        throw new AppDisableError(app.app);
+      }
+      const plugins = service.plugins(app, session, store);
+      for (const options of plugins) {
+        session.plugins.add(options, app.id);
+      }
+      service.beforeSessionStart(app, session);
+    }
+  }
+
+  async afterSessionStart(session: WhatsappSession, store: DataStore) {
+    const knex = store.getWAHADatabase();
+    const repo = new AppRepository(knex);
+    const apps = await repo.getEnabledBySession(session.name);
+    for (const app of apps) {
+      const service = this.getAppService(app);
+      if (!service && !AppRuntimeConfig.HasApp(app.app)) {
+        throw new AppDisableError(app.app);
+      }
+      service.afterSessionStart(app, session);
+    }
+  }
+
+  async syncSessionApps(
+    manager: SessionManager,
+    session: string,
+    apps: App[],
+  ): Promise<void> {
+    // Reject duplicate unique apps in the payload before any writes,
+    // otherwise the by-type matching below binds them to the same app
+    const duplicateUniqueApp = findDuplicateUniqueApp(apps);
+    if (duplicateUniqueApp !== null) {
+      throw new UnprocessableEntityException(
+        `Only one '${duplicateUniqueApp}' app is allowed per session - remove duplicate entries from 'apps'.`,
+      );
+    }
+
+    const existing = await this.list(manager, session);
+    const ids = new Set<string>();
+
+    // Upsert provided apps
+    for (const app of apps) {
+      if (!app.id) {
+        //  Try to find the app by type
+        const found = existing.find((a) => a.app === app.app);
+        if (found) {
+          app.id = found.id;
+        }
+      }
+      // Force session
+      app.session = session;
+      await this.upsert(manager, app);
+      ids.add(app.id);
+    }
+
+    // Remove apps that are not in the provided list
+    for (const app of existing) {
+      if (ids.has(app.id)) {
+        continue;
+      }
+      await this.delete(manager, app.id);
+    }
+  }
+
+  async migrate(knex: Knex): Promise<void> {
+    await migrate(knex);
+  }
+
+  private getAppService(app: App): IAppService | null {
+    const appModule = GetApp(app.app);
+    if (!appModule) {
+      throw new Error(`App '${app.app}' not supported`);
+    }
+    try {
+      return this.moduleRef.get(appModule.Service, { strict: false });
+    } catch {
+      // Provider is not registered - app is disabled via WAHA_APPS_ON / WAHA_APPS_OFF
+      return null;
+    }
+  }
+
+  private async checkSessionExists(
+    manager: SessionManager,
+    sessionName: string,
+  ) {
+    const session = await manager.exists(sessionName);
+    if (session === null) {
+      throw new NotFoundException('Session not found');
+    }
+  }
+}

src/apps/app_sdk/services/IAppService.ts

@@ -0,0 +1,79 @@
+import { App } from '@waha/apps/app_sdk/dto/app.dto';
+import { DataStore } from '@waha/core/abc/DataStore';
+import { SessionManager } from '@waha/core/abc/manager.abc';
+import { WhatsappSession } from '@waha/core/abc/session.abc';
+import { PluginOptions } from '@waha/core/abc/session.plugin';
+
+/**
+ * Exact App service
+ */
+export interface IAppService {
+  validate(app: App): void;
+
+  beforeCreated(app: App): Promise<void>;
+
+  /**
+   * Called after the app record is saved to the database during creation.
+   * Use this for side effects that must happen after the app exists in storage.
+   */
+  afterCreated(manager: SessionManager, app: App): Promise<void>;
+
+  /**
+   * Called only when the app transitions from disabled -> enabled.
+   */
+  beforeEnabled(
+    manager: SessionManager,
+    savedApp: App,
+    newApp: App,
+  ): Promise<void>;
+
+  /**
+   * Called only when the app transitions from enabled -> disabled.
+   */
+  beforeDisabled(
+    manager: SessionManager,
+    savedApp: App,
+    newApp: App,
+  ): Promise<void>;
+
+  beforeUpdated(
+    manager: SessionManager,
+    savedApp: App,
+    newApp: App,
+  ): Promise<void>;
+
+  beforeDeleted(manager: SessionManager, app: App): Promise<void>;
+
+  /**
+   * Deletes the app's stored data (database rows, caches) while keeping the app configured.
+   * Apps without storage implement it as a no-op.
+   */
+  purge(manager: SessionManager, app: App): Promise<void>;
+
+  /**
+   * Called for each app before a bulk session deletion removes all app records.
+   * Use this to clean up external resources tied to the app (e.g. API keys).
+   */
+  beforeSessionDeleted(manager: SessionManager, app: App): Promise<void>;
+
+  /**
+   * Called after reading an app from storage, before returning it to the caller.
+   * Use this to populate transient fields that are not persisted (e.g. secret values).
+   */
+  enrich(manager: SessionManager, app: App): Promise<void>;
+
+  /**
+   * Session plugins contributed by this app. AppsEnabledService registers them with the app id,
+   * and the session manager attaches their hooks and events before session.start().
+   * store - the server data store, for apps whose plugins persist data.
+   */
+  plugins(
+    app: App,
+    session: WhatsappSession,
+    store?: DataStore,
+  ): PluginOptions[];
+
+  beforeSessionStart(app: App, session: WhatsappSession): void;
+
+  afterSessionStart(app: App, session: WhatsappSession): void;
+}