feat: implement PAPI license management for interactive messages

- Added a LicenseService to manage PAPI license initialization and validation for interactive messages (buttons, lists, carousel).
- Updated sendMessage controller to check license status before sending interactive messages, throwing ForbiddenException if the license is invalid.
- Enhanced README with details on interactive messages and license requirements.
- Updated .gitignore to exclude machine ID file related to PAPI license.

Author: DavidsonGomes

.gitignore

@@ -46,3 +46,6 @@ lerna-debug.log*
 .tool-versions
 
 /prisma/migrations/*
+
+# PAPI License machine ID (should not be committed)
+.machine-id

README.md

@@ -42,6 +42,34 @@ Evolution API supports multiple types of connections to WhatsApp, enabling flexi
   - The Cloud API supports features such as end-to-end encryption, advanced analytics, and more comprehensive customer service tools.
   - To use this API, you must comply with Meta's policies and potentially pay for usage based on message volume and other factors.
 
+## Interactive Messages
+
+Evolution API uses [PAPI (Pastorini API)](https://github.com/mktpastorini/papi) as a Git submodule to provide robust support for interactive WhatsApp messages. PAPI is integrated directly into the codebase and powers the following features:
+
+- **Interactive Buttons**: Send reply buttons, URL buttons, call buttons, and copy code buttons
+- **List Messages**: Create interactive menus with sections and options
+- **Carousel Messages**: Send carousel cards with images, videos, and buttons
+
+These interactive message types are fully integrated and work seamlessly with Evolution API's instance management system. The PAPI library is included as a required submodule and is automatically updated when you pull the repository with `--recursive` or update submodules.
+
+**Note**: When cloning the repository, make sure to use `git clone --recursive` or run `git submodule update --init --recursive` after cloning to ensure the PAPI submodule is properly initialized.
+
+### License Requirement
+
+Interactive messages (buttons, lists, and carousel) require a valid PAPI license to function. To obtain a license key:
+
+1. **Register for a license**: Visit [https://padmin.intrategica.com.br/register.html](https://padmin.intrategica.com.br/register.html) to create an account and request a license key
+2. **Support the project**: Consider contributing to the [PAPI crowdfunding campaign](https://papi.mundoautomatik.com/) to help fund the development of new features
+
+Once you have your license key, configure it in your `.env` file:
+
+```env
+PAPI_LICENSE_KEY=your_license_key_here
+PAPI_LICENSE_ADMIN_URL=https://padmin.intrategica.com.br/
+```
+
+If no license is configured, interactive messages will be disabled. The license system verifies your license status periodically and blocks interactive messages if the license is invalid, expired, or blocked.
+
 ## Integrations
 
 Evolution API supports various integrations to enhance its functionality. Below is a list of available integrations and their uses:

src/api/controllers/sendMessage.controller.ts

@@ -15,8 +15,9 @@ import {
   SendTemplateDto,
   SendTextDto,
 } from '@api/dto/sendMessage.dto';
+import { licenseService } from '@api/services/license.service';
 import { WAMonitoringService } from '@api/services/monitor.service';
-import { BadRequestException } from '@exceptions';
+import { BadRequestException, ForbiddenException } from '@exceptions';
 import { isBase64, isURL } from 'class-validator';
 import emojiRegex from 'emoji-regex';
 
@@ -76,10 +77,22 @@ export class SendMessageController {
   }
 
   public async sendButtons({ instanceName }: InstanceDto, data: SendButtonsDto) {
+    if (!(await licenseService.isAllowed())) {
+      const status = await licenseService.getStatus();
+      throw new ForbiddenException(
+        `Interactive messages (buttons) are blocked. License status: ${status.status}. ${status.message}`,
+      );
+    }
     return await this.waMonitor.waInstances[instanceName].buttonMessage(data);
   }
 
   public async sendCarousel({ instanceName }: InstanceDto, data: SendCarouselDto) {
+    if (!(await licenseService.isAllowed())) {
+      const status = await licenseService.getStatus();
+      throw new ForbiddenException(
+        `Interactive messages (carousel) are blocked. License status: ${status.status}. ${status.message}`,
+      );
+    }
     return await this.waMonitor.waInstances[instanceName].carouselMessage(data);
   }
 
@@ -88,6 +101,13 @@ export class SendMessageController {
   }
 
   public async sendList({ instanceName }: InstanceDto, data: SendListDto) {
+    const instancesCount = Object.keys(this.waMonitor.waInstances).length;
+    if (!(await licenseService.isAllowed(instancesCount))) {
+      const status = await licenseService.getStatus();
+      throw new ForbiddenException(
+        `Interactive messages (list) are blocked. License status: ${status.status}. ${status.message}`,
+      );
+    }
     return await this.waMonitor.waInstances[instanceName].listMessage(data);
   }
 

src/api/services/license.service.ts

@@ -0,0 +1,152 @@
+import { configService, PapiLicense } from '@config/env.config';
+import { Logger } from '@config/logger.config';
+
+import licenseManager from '../../../papi/lib/License/licenseManager.js';
+
+export class LicenseService {
+  private logger = new Logger('LICENSE');
+  private initialized = false;
+  private initializing = false;
+
+  /**
+   * Initialize license manager with environment variables (lazy initialization)
+   * Only initializes when interactive messages are actually used
+   */
+  private async ensureInitialized(): Promise<void> {
+    // Se já está inicializado, retorna
+    if (this.initialized) {
+      return;
+    }
+
+    // Se já está inicializando, aguarda
+    if (this.initializing) {
+      // Aguarda até 5 segundos para a inicialização completar
+      let attempts = 0;
+      while (this.initializing && attempts < 50) {
+        await new Promise((resolve) => setTimeout(resolve, 100));
+        attempts++;
+      }
+      return;
+    }
+
+    this.initializing = true;
+
+    try {
+      const licenseConfig = configService.get<PapiLicense>('PAPI_LICENSE');
+
+      // Se não há configuração de licença, bloqueia mensagens interativas
+      if (!licenseConfig.KEY || !licenseConfig.ADMIN_URL) {
+        this.logger.warn(
+          '⚠️ PAPI License not configured - Interactive messages (buttons, lists, carousel) will be BLOCKED',
+        );
+        this.logger.warn(
+          'To enable interactive messages, configure PAPI_LICENSE_KEY and PAPI_LICENSE_ADMIN_URL in your .env file',
+        );
+        this.logger.warn('Get your license key at: https://padmin.intrategica.com.br/register.html');
+        this.initializing = false;
+        return;
+      }
+
+      this.logger.verbose('Initializing PAPI License Manager...');
+
+      await licenseManager.initialize(licenseConfig.KEY, licenseConfig.ADMIN_URL);
+
+      // Set callback for when license is blocked
+      licenseManager.onBlock(() => {
+        this.logger.error('⚠️ PAPI License has been BLOCKED - Interactive messages are now disabled');
+      });
+
+      const initialStatus = licenseManager.getStatus();
+
+      if (initialStatus.status === 'PENDING_ACTIVATION') {
+        this.logger.warn(
+          '⏳ PAPI License is pending activation - Interactive messages will be blocked until activation',
+        );
+      } else if (initialStatus.status === 'MACHINE_MISMATCH') {
+        this.logger.error('❌ PAPI License is bound to another server - Interactive messages are disabled');
+      } else if (initialStatus.status === 'ACTIVE') {
+        this.logger.info(`✓ PAPI License is ACTIVE - Interactive messages enabled`);
+      } else {
+        this.logger.warn(`PAPI License status: ${initialStatus.status} - ${initialStatus.message}`);
+      }
+
+      this.initialized = true;
+    } catch (error) {
+      this.logger.error(`Failed to initialize PAPI License Manager: ${error}`);
+      // Não bloqueia a inicialização, mas marca como não inicializado
+    } finally {
+      this.initializing = false;
+    }
+  }
+
+  /**
+   * Check if interactive messages are allowed (buttons, lists, carousel)
+   * Initializes license manager on first use (lazy initialization)
+   * Updates instance count when checking (replaces periodic updates)
+   */
+  public async isAllowed(instancesCount?: number): Promise<boolean> {
+    const licenseConfig = configService.get<PapiLicense>('PAPI_LICENSE');
+
+    // Se não há configuração de licença, bloqueia mensagens interativas
+    if (!licenseConfig.KEY || !licenseConfig.ADMIN_URL) {
+      return false;
+    }
+
+    // Inicializa se ainda não foi inicializado (lazy initialization)
+    await this.ensureInitialized();
+
+    // Se não foi inicializado após tentativa, bloqueia por segurança
+    if (!this.initialized) {
+      return false;
+    }
+
+    // Atualiza contagem de instâncias quando verificar (substitui atualização periódica)
+    if (instancesCount !== undefined) {
+      licenseManager.setInstancesCount(instancesCount);
+    }
+
+    return licenseManager.isAllowed();
+  }
+
+  /**
+   * Get current license status
+   * Initializes license manager on first use (lazy initialization)
+   */
+  public async getStatus() {
+    const licenseConfig = configService.get<PapiLicense>('PAPI_LICENSE');
+
+    if (!licenseConfig.KEY || !licenseConfig.ADMIN_URL) {
+      return {
+        isValid: false,
+        status: 'NOT_CONFIGURED' as const,
+        message: 'License key and admin URL must be configured',
+      };
+    }
+
+    // Inicializa se ainda não foi inicializado (lazy initialization)
+    await this.ensureInitialized();
+
+    if (!this.initialized) {
+      return {
+        isValid: false,
+        status: 'NOT_INITIALIZED' as const,
+        message: 'License manager not initialized',
+      };
+    }
+
+    return licenseManager.getStatus();
+  }
+
+  /**
+   * Update instances count for heartbeat
+   * Called only when interactive messages are used (not periodically)
+   * @deprecated Use isAllowed(instancesCount) instead
+   */
+  public setInstancesCount(count: number): void {
+    if (this.initialized) {
+      licenseManager.setInstancesCount(count);
+    }
+  }
+}
+
+export const licenseService = new LicenseService();

src/config/env.config.ts

@@ -370,6 +370,11 @@ export type EventEmitter = {
   MAX_LISTENERS: number;
 };
 
+export type PapiLicense = {
+  KEY?: string;
+  ADMIN_URL?: string;
+};
+
 export type Production = boolean;
 
 export interface Env {
@@ -403,6 +408,7 @@ export interface Env {
   FACEBOOK: Facebook;
   SENTRY: Sentry;
   EVENT_EMITTER: EventEmitter;
+  PAPI_LICENSE: PapiLicense;
   PRODUCTION?: Production;
 }
 
@@ -846,6 +852,10 @@ export class ConfigService {
       EVENT_EMITTER: {
         MAX_LISTENERS: Number.parseInt(process.env?.EVENT_EMITTER_MAX_LISTENERS) || 50,
       },
+      PAPI_LICENSE: {
+        KEY: process.env?.PAPI_LICENSE_KEY,
+        ADMIN_URL: process.env?.PAPI_LICENSE_ADMIN_URL || 'https://padmin.intrategica.com.br/',
+      },
     };
   }
 }

src/main.ts

@@ -44,6 +44,8 @@ async function bootstrap() {
   const prismaRepository = new PrismaRepository(configService);
   await prismaRepository.onModuleInit();
 
+  // PAPI License Manager will be initialized lazily when interactive messages are first used
+
   app.use(
     cors({
       origin(requestOrigin, callback) {
@@ -163,6 +165,9 @@ async function bootstrap() {
     logger.error('Error loading instances: ' + error);
   });
 
+  // License manager heartbeat is handled internally by the PAPI licenseManager
+  // Instance count is updated only when interactive messages are used (lazy initialization)
+
   onUnexpectedError();
 }