Changelog¶

All notable changes to Wappa will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

[0.2.1] - 2026-01-12¶

🎉 New Features¶

State Handler API¶

• Message-Agnostic State Management: New REST API for assigning state handlers to users after ANY message type
• POST /api/whatsapp/state-handlers/set - Assign handler with TTL and context
• GET /api/whatsapp/state-handlers/get/{recipient}/{handler_value} - Retrieve handler state
• DELETE /api/whatsapp/state-handlers/delete/{recipient}/{handler_value} - Remove handler
• Cache key pattern: api-handler-{handler_value}
• TTL support: 60-86400 seconds (1 minute to 24 hours)
• Optional initial context for handler configuration
• Perfect for automation workflows and multi-step conversational flows

AI Context for Media Messages¶

• Description Field: New optional field for all media message types (image, video, audio, document, sticker)
• Separate from caption (caption = user-visible, description = AI context)
• Max 2048 characters for rich AI agent context
• NOT sent to WhatsApp - internal context only
• Helps AI agents understand sent media content
• Improves conversational intelligence and context awareness

🔧 Improvements¶

Code Quality¶

• Added logging to HandlerStateService for better observability
• Extracted STATE_KEY_PREFIX constant to eliminate magic strings
• Created _make_state_key() helper method for DRY principle
• Consolidated media description field using AI_DESCRIPTION_FIELD constant
• Reduced ~40 lines of duplicated code across media models

Documentation¶

• New REST API Reference: Comprehensive documentation for all WhatsApp REST endpoints
• Complete examples for text, media, interactive, and template messages
• State handler management patterns and use cases
• AI context usage examples
• Error handling and rate limit guidance
• Interactive API documentation at /docs endpoint

0.2.0 - 2026-01-11¶

🎉 Major Features¶

Database Plugin System¶

• PostgresDatabasePlugin: Full async PostgreSQL support with session management inspired by 30x-community patterns
• Async conversational app optimization with connection pooling
• Smart session lifecycle management
• Automatic reconnection handling
• Query result caching for performance

Redis PubSub Plugin¶

• Multi-tenant Redis PubSub: Enterprise-grade publish/subscribe messaging
• Multi-tenant channel isolation
• Self-subscribing example demonstrating real-time messaging
• Channel pattern matching
• Message broadcasting across app instances

AIState & Cache Enhancements¶

• AIState Pool System: Multi-backend AI state management (Pool 4)
• Support for Memory, JSON, and Redis backends
• Automatic state persistence and recovery
• TTL-based state expiration

• Cross-session state continuity

• ExpiryActions System: SOLID architecture for TTL-based actions

• Automatic action triggers on cache expiration
• Configurable expiry handlers
• Comprehensive example implementation
• Clean separation of concerns

🔧 Improvements¶

API & Schema Updates¶

• WhatsApp API v24.0+ BSUID Support: Latest WhatsApp Business API features
• Business-Scoped User ID (BSUID) support
• Enhanced user identification across conversations

• Improved privacy compliance

• Media Message Schemas: Added url field to all media message types

• Images, videos, audio, documents now include direct URL access
• Simplified media relay and file serving

• Better integration with CDN workflows

• API Response Field Names: Corrected api_response field naming

• Consistent field naming across template and specialized handlers
• Better type safety and IDE autocomplete

State Management¶

• Template State Handling: Comprehensive API tracking for template messages
• State caching for template API responses
• Route optimization based on message state

• Better conversation flow with template messages

• API Message Events: New event system for message lifecycle

• message_sent, message_delivered, message_read events
• Route optimization for event handlers
• Real-time message status tracking

🏗️ Architecture & Refactoring¶

SOLID Principles Implementation¶

• Comprehensive API Refactoring: Applied SOLID principles across codebase
• Single Responsibility: Clear separation of concerns
• Open/Closed: Plugin-based extensibility
• Liskov Substitution: Proper interface inheritance
• Interface Segregation: Type-specific cache interfaces
• Dependency Inversion: Dependency injection throughout

Type-Specific Cache Interfaces¶

• Migrated Examples: All example projects now use type-specific cache interfaces
• StateCache, UserCache, TableCache with proper typing
• Pydantic BaseModel support across all cache types
• Better compile-time type checking
• Improved IDE autocomplete and error detection

Example Projects Improvements¶

• db_redis_echo_example: Complete SOLID refactoring
• Clean architecture with separated concerns
• Settings class replacing direct os.getenv calls
• Modular score system

• Production-ready error handling

• redis_pubsub_example: New self-subscribing example

• Demonstrates real-time messaging patterns
• Multi-tenant channel isolation
• Event-driven architecture

🛠️ CLI Enhancements¶

New Example Projects in CLI¶

• db_redis_echo_example: Added to wappa examples menu
• Interactive database + Redis demonstration
• User management with PostgreSQL

• Session tracking and analytics

• redis_pubsub_example: Added to wappa examples menu

• Real-time messaging demonstration
• Multi-channel subscription patterns
• Broadcast messaging capabilities

🐛 Bug Fixes¶

• Media Schema URL Field: Fixed missing url field in media message schemas (commit 5af6f4c)
• Template API Response: Corrected api_response field name in template handlers (commit 2cad8a0)
• Schema Cleanup: Removed duplicate outdated webhook interfaces (commit c651058)
• Cache Interface Migration: Fixed example projects cache interface usage (commit a511660)

📦 Dependencies¶

• asyncpg: Added for async PostgreSQL support with ruff formatting applied

🔄 Breaking Changes¶

None. Version 0.2.0 maintains full backward compatibility with 0.1.x releases.

📚 Documentation¶

• Comprehensive documentation updates for all new features
• New plugin documentation for PostgresDatabasePlugin and Redis PubSub
• Updated cache documentation with AIState Pool and ExpiryActions
• Enhanced examples documentation with new project templates
• API reference updates for WhatsApp v24.0+ features

🙏 Credits¶

Special thanks to: - 30x-community for session management inspiration in PostgresDatabasePlugin - All contributors who provided feedback and bug reports

0.1.0 - Initial Release¶

• Initial release of Wappa WhatsApp framework
• Core messaging functionality
• Event handling system
• Cache backends (Memory, JSON, Redis)
• CLI tools for project initialization
• Example projects
• Full WhatsApp Business API integration